# README
Cloud Logging 
For an interactive tutorial on using the client library in a Go application, click Guide Me.
Example Usage
First create a logging.Client to use throughout your application:
[snip]:# (logging-1)
ctx := context.Background()
client, err := logging.NewClient(ctx, "my-project")
if err != nil {
// TODO: Handle error.
}
Usually, you'll want to add log entries to a buffer to be periodically flushed (automatically and asynchronously) to the Cloud Logging service. [snip]:# (logging-2)
logger := client.Logger("my-log")
logger.Log(logging.Entry{Payload: "something happened!"})
If you need to write a critical log entry use synchronous ingestion method. [snip]:# (logging-3)
logger := client.Logger("my-log")
logger.LogSync(context.Background(), logging.Entry{Payload: "something happened!"})
Close your client before your program exits, to flush any buffered log entries. [snip]:# (logging-4)
err = client.Close()
if err != nil {
// TODO: Handle error.
}
Logger configuration options
Creating a Logger using logging.Logger accept configuration LoggerOption arguments. The following options are supported:
| Configuration option | Arguments | Description |
|---|---|---|
| CommonLabels | map[string]string | The set of labels that will be ingested for all log entries ingested by Logger. |
| ConcurrentWriteLimit | int | Number of parallel goroutine the Logger will use to ingest logs asynchronously. High number of routines may exhaust API quota. The default is 1. |
| DelayThreshold | time.Duration | Maximum time a log entry is buffered on client before being ingested. The default is 1 second. |
| EntryCountThreshold | int | Maximum number of log entries to be buffered on client before being ingested. The default is 1000. |
| EntryByteThreshold | int | Maximum size in bytes of log entries to be buffered on client before being ingested. The default is 8MiB. |
| EntryByteLimit | int | Maximum size in bytes of the single write call to ingest log entries. If EntryByteLimit is smaller than EntryByteThreshold, the latter has no effect. The default is zero, meaning there is no limit. |
| BufferedByteLimit | int | Maximum number of bytes that the Logger will keep in memory before returning ErrOverflow. This option limits the total memory consumption of the Logger (but note that each Logger has its own, separate limit). It is possible to reach BufferedByteLimit even if it is larger than EntryByteThreshold or EntryByteLimit, because calls triggered by the latter two options may be enqueued (and hence occupying memory) while new log entries are being added. |
| ContextFunc | func() (ctx context.Context, afterCall func()) | Callback function to be called to obtain context.Context during async log ingestion. |
| SourceLocationPopulation | One of logging.DoNotPopulateSourceLocation, logging.PopulateSourceLocationForDebugEntries or logging.AlwaysPopulateSourceLocation | Controls auto-population of the logging.Entry.SourceLocation field when ingesting log entries. Allows to disable population of source location info, allowing it only for log entries at Debug severity or enable it for all log entries. Enabling it for all entries may result in degradation in performance. Use logging_test.BenchmarkSourceLocationPopulation to test performance with and without the option. The default is set to logging.DoNotPopulateSourceLocation. |
| PartialSuccess | Make each write call to Logging service with partialSuccess flag set. The default is to make calls without setting the flag. | |
| RedirectAsJSON | io.Writer | Converts log entries to Jsonified one line string according to the structured logging format and writes it to provided io.Writer. Users should use this option with os.Stdout and os.Stderr to leverage the out-of-process ingestion of logs using logging agents that are deployed in Cloud Logging environments. |
# Functions
BufferedByteLimit is the maximum number of bytes that the Logger will keep in memory before returning ErrOverflow.
CommonLabels are labels that apply to all log entries written from a Logger, so that you don't have to repeat them in each log entry's Labels field.
CommonResource sets the monitored resource associated with all log entries written from a Logger.
ConcurrentWriteLimit determines how many goroutines will send log entries to the underlying service.
ContextFunc is a function that will be called to obtain a context.Context for the WriteLogEntries RPC executed in the background for calls to Logger.Log.
DelayThreshold is the maximum amount of time that an entry should remain buffered in memory before a call to the logging service is triggered.
EntryByteLimit is the maximum number of bytes of entries that will be sent in a single call to the logging service.
EntryByteThreshold is the maximum number of bytes of entries that will be buffered in memory before a call to the logging service is triggered.
EntryCountThreshold is the maximum number of entries that will be buffered in memory before a call to the logging service is triggered.
NewClient returns a new logging client associated with the provided parent.
ParseSeverity returns the Severity whose name equals s, ignoring case.
PartialSuccess sets the partialSuccess flag to true when ingesting a bundle of log entries.
RedirectAsJSON instructs Logger to redirect output of calls to Log and LogSync to provided io.Writer instead of ingesting to Cloud Logging.
SourceLocationPopulation is the flag controlling population of the source location info in the ingested entries.
ToLogEntry takes an Entry structure and converts it to the LogEntry proto.
# Constants
AdminScope is the scope for administrative actions on the logging service.
Alert means a person must take an action immediately.
AlwaysPopulateSourceLocation is set when WithSourceLocation(PopulateAllEntries) is provided.
Critical means events that cause more severe problems or brief outages.
Debug means debug or trace information.
Default means the log entry has no assigned severity level.
1GiB.
9.5 MiB.
DefaultDelayThreshold is the default value for the DelayThreshold LoggerOption.
8MiB.
DefaultEntryCountThreshold is the default value for the EntryCountThreshold LoggerOption.
DetectProjectID is a sentinel value that instructs NewClient to detect the project ID.
DoNotPopulateSourceLocation is default for clients when WithSourceLocation is not provided.
Emergency means one or more systems are unusable.
Error means events that are likely to cause problems.
Info means routine information, such as ongoing status or performance.
Notice means normal but significant events, such as start up, shut down, or configuration.
PopulateSourceLocationForDebugEntries is set when WithSourceLocation(PopulateDebugEntries) is provided.
ReadScope is the scope for reading from the logging service.
Warning means events that might cause problems.
WriteScope is the scope for writing to the logging service.
# Variables
ErrOverflow signals that the number of buffered entries for a Logger exceeds its BufferLimit.
ErrOversizedEntry signals that an entry's size exceeds the maximum number of bytes that will be sent in a single call to the logging service.
ErrRedirectProtoPayloadNotSupported is returned when Logger is configured to redirect output and tries to redirect logs with protobuf payload.
# Structs
Client is a Logging client.
Entry is a log entry.
HTTPRequest contains an http.Request as well as additional information about the request and its response.
A Logger is used to write log messages to a single log.
# Interfaces
LoggerOption is a configuration option for a Logger.
# Type aliases
Severity is the severity of the event described in a log entry.