Documentation ¶
Overview ¶
Package logging contains a Stackdriver Logging client suitable for writing logs. For reading logs, and working with sinks, metrics and monitored resources, see package cloud.google.com/go/logging/logadmin.
This client uses Logging API v2. See https://cloud.google.com/logging/docs/api/v2/ for an introduction to the API.
This package is experimental and subject to API changes.
Creating a Client ¶
Use a Client to interact with the Stackdriver Logging API.
// Create a Client ctx := context.Background() client, err := logging.NewClient(ctx, "my-project") if err != nil { // TODO: Handle error. }
Basic Usage ¶
For most use-cases, you'll want to add log entries to a buffer to be periodically flushed (automatically and asynchronously) to the Stackdriver Logging service.
// Initialize a logger lg := client.Logger("my-log") // Add entry to log buffer lg.Log(logging.Entry{Payload: "something happened!"})
Closing your Client ¶
You should call Client.Close before your program exits to flush any buffered log entries to the Stackdriver Logging service.
// Close the client when finished. err = client.Close() if err != nil { // TODO: Handle error. }
Synchronous Logging ¶
For critical errors, you may want to send your log entries immediately. LogSync is slow and will block until the log entry has been sent, so it is not recommended for basic use.
lg.LogSync(ctx, logging.Entry{Payload: "ALERT! Something critical happened!"})
The Standard Logger Interface ¶
You may want use a standard log.Logger in your program.
// stdlg implements log.Logger stdlg := lg.StandardLogger(logging.Info) stdlg.Println("some info")
Log Levels ¶
An Entry may have one of a number of severity levels associated with it.
logging.Entry{ Payload: "something terrible happened!", Severity: logging.Critical, }
Index ¶
- Constants
- Variables
- type Client
- type Entry
- type HTTPRequest
- type Logger
- type LoggerOption
- func BufferedByteLimit(n int) LoggerOption
- func CommonLabels(m map[string]string) LoggerOption
- func CommonResource(r *mrpb.MonitoredResource) LoggerOption
- func DelayThreshold(d time.Duration) LoggerOption
- func EntryByteLimit(n int) LoggerOption
- func EntryByteThreshold(n int) LoggerOption
- func EntryCountThreshold(n int) LoggerOption
- type Severity
Examples ¶
Constants ¶
const ( // Scope for reading from the logging service. ReadScope = "https://www.googleapis.com/auth/logging.read" // Scope for writing to the logging service. WriteScope = "https://www.googleapis.com/auth/logging.write" // Scope for administrative actions on the logging service. AdminScope = "https://www.googleapis.com/auth/logging.admin" )
const ( // DefaultDelayThreshold is the default value for the DelayThreshold LoggerOption. DefaultDelayThreshold = time.Second // DefaultEntryCountThreshold is the default value for the EntryCountThreshold LoggerOption. DefaultEntryCountThreshold = 10 // DefaultEntryByteThreshold is the default value for the EntryByteThreshold LoggerOption. DefaultEntryByteThreshold = 1 << 20 // 1MiB // DefaultBufferedByteLimit is the default value for the BufferedByteLimit LoggerOption. DefaultBufferedByteLimit = 1 << 30 // 1GiB )
const ( // Default means the log entry has no assigned severity level. Default = Severity(logtypepb.LogSeverity_DEFAULT) // Debug means debug or trace information. Debug = Severity(logtypepb.LogSeverity_DEBUG) // Info means routine information, such as ongoing status or performance. Info = Severity(logtypepb.LogSeverity_INFO) // Notice means normal but significant events, such as start up, shut down, or configuration. Notice = Severity(logtypepb.LogSeverity_NOTICE) // Warning means events that might cause problems. Warning = Severity(logtypepb.LogSeverity_WARNING) // Error means events that are likely to cause problems. Error = Severity(logtypepb.LogSeverity_ERROR) // Critical means events that cause more severe problems or brief outages. Critical = Severity(logtypepb.LogSeverity_CRITICAL) // Alert means a person must take an action immediately. Alert = Severity(logtypepb.LogSeverity_ALERT) // Emergency means one or more systems are unusable. Emergency = Severity(logtypepb.LogSeverity_EMERGENCY) )
Variables ¶
var ErrOverflow = errors.New("logging: log entry overflowed buffer limits")
ErrOverflow signals that the number of buffered entries for a Logger exceeds its BufferLimit.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct { // OnError is called when an error occurs in a call to Log or Flush. The // error may be due to an invalid Entry, an overflow because BufferLimit // was reached (in which case the error will be ErrOverflow) or an error // communicating with the logging service. OnError is called with errors // from all Loggers. It is never called concurrently. OnError is expected // to return quickly; if errors occur while OnError is running, some may // not be reported. The default behavior is to call log.Printf. // // This field should be set only once, before any method of Client is called. OnError func(err error) // contains filtered or unexported fields }
Client is a Logging client. A Client is associated with a single Cloud project.
func NewClient ¶
NewClient returns a new logging client associated with the provided project ID.
By default NewClient uses WriteScope. To use a different scope, call NewClient using a WithScopes option (see https://godoc.org/google.golang.org/api/option#WithScopes).
Example ¶
package main import ( "cloud.google.com/go/preview/logging" "golang.org/x/net/context" ) func main() { ctx := context.Background() client, err := logging.NewClient(ctx, "my-project") if err != nil { // TODO: Handle error. } // Use client to manage logs, metrics and sinks. // Close the client when finished. if err := client.Close(); err != nil { // TODO: Handle error. } }
Output:
Example (ErrorFunc) ¶
package main import ( "fmt" "os" "cloud.google.com/go/preview/logging" "golang.org/x/net/context" ) func main() { ctx := context.Background() client, err := logging.NewClient(ctx, "my-project") if err != nil { // TODO: Handle error. } // Print all errors to stdout. client.OnError = func(e error) { fmt.Fprintf(os.Stdout, "logging: %v", e) } // Use client to manage logs, metrics and sinks. // Close the client when finished. if err := client.Close(); err != nil { // TODO: Handle error. } }
Output:
func (*Client) Close ¶
Close flushes any pending log entries then closes the client. Failing to call this method before the program exits may result in dropped entries.
func (*Client) Logger ¶
func (c *Client) Logger(logID string, opts ...LoggerOption) *Logger
Logger returns a Logger that will write entries with the given log ID, such as "syslog". A log ID must be less than 512 characters long and can only include the following characters: upper and lower case alphanumeric characters: [A-Za-z0-9]; and punctuation characters: forward-slash, underscore, hyphen, and period.
Example ¶
package main import ( "cloud.google.com/go/preview/logging" "golang.org/x/net/context" ) func main() { ctx := context.Background() client, err := logging.NewClient(ctx, "my-project") if err != nil { // TODO: Handle error. } lg := client.Logger("my-log") _ = lg // TODO: use the Logger. }
Output:
func (*Client) Ping ¶
Ping reports whether the client's connection to the logging service and the authentication configuration are valid. To accomplish this, Ping writes a log entry "ping" to a log named "ping".
Example ¶
package main import ( "cloud.google.com/go/preview/logging" "golang.org/x/net/context" ) func main() { ctx := context.Background() client, err := logging.NewClient(ctx, "my-project") if err != nil { // TODO: Handle error. } if err := client.Ping(ctx); err != nil { // TODO: Handle error. } }
Output:
type Entry ¶
type Entry struct { // Timestamp is the time of the entry. If zero, the current time is used. Timestamp time.Time // Severity is the entry's severity level. // The zero value is Default. Severity Severity // Payload must be either a string or something that // marshals via the encoding/json package to a JSON object // (and not any other type of JSON value). Payload interface{} // Labels optionally specifies key/value labels for the log entry. // The Logger.Log method takes ownership of this map. See Logger.CommonLabels // for more about labels. Labels map[string]string // InsertID is a unique ID for the log entry. If you provide this field, // the logging service considers other log entries in the same log with the // same ID as duplicates which can be removed. If omitted, the logging // service will generate a unique ID for this log entry. Note that because // this client retries RPCs automatically, it is possible (though unlikely) // that an Entry without an InsertID will be written more than once. InsertID string // HTTPRequest optionally specifies metadata about the HTTP request // associated with this log entry, if applicable. It is optional. HTTPRequest *HTTPRequest // Operation optionally provides information about an operation associated // with the log entry, if applicable. Operation *logpb.LogEntryOperation // LogName is the full log name, in the form // "projects/{ProjectID}/logs/{LogID}". It is set by the client when // reading entries. It is an error to set it when writing entries. LogName string // Resource is the monitored resource associated with the entry. It is set // by the client when reading entries. It is an error to set it when // writing entries. Resource *mrpb.MonitoredResource }
Entry is a log entry. See https://cloud.google.com/logging/docs/view/logs_index for more about entries.
type HTTPRequest ¶
type HTTPRequest struct { // Request is the http.Request passed to the handler. Request *http.Request // RequestSize is the size of the HTTP request message in bytes, including // the request headers and the request body. RequestSize int64 // Status is the response code indicating the status of the response. // Examples: 200, 404. Status int // ResponseSize is the size of the HTTP response message sent back to the client, in bytes, // including the response headers and the response body. ResponseSize int64 // RemoteIP is the IP address (IPv4 or IPv6) of the client that issued the // HTTP request. Examples: "192.168.1.1", "FE80::0202:B3FF:FE1E:8329". RemoteIP string // CacheHit reports whether an entity was served from cache (with or without // validation). CacheHit bool // CacheValidatedWithOriginServer reports whether the response was // validated with the origin server before being served from cache. This // field is only meaningful if CacheHit is true. CacheValidatedWithOriginServer bool }
HTTPRequest contains an http.Request as well as additional information about the request and its response.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
A Logger is used to write log messages to a single log. It can be configured with a log ID, common monitored resource, and a set of common labels.
func (*Logger) Flush ¶
func (l *Logger) Flush()
Flush blocks until all currently buffered log entries are sent.
Example ¶
package main import ( "cloud.google.com/go/preview/logging" "golang.org/x/net/context" ) func main() { ctx := context.Background() client, err := logging.NewClient(ctx, "my-project") if err != nil { // TODO: Handle error. } lg := client.Logger("my-log") lg.Log(logging.Entry{Payload: "something happened"}) lg.Flush() }
Output:
func (*Logger) Log ¶
Log buffers the Entry for output to the logging service. It never blocks.
Example ¶
package main import ( "cloud.google.com/go/preview/logging" "golang.org/x/net/context" ) func main() { ctx := context.Background() client, err := logging.NewClient(ctx, "my-project") if err != nil { // TODO: Handle error. } lg := client.Logger("my-log") lg.Log(logging.Entry{Payload: "something happened"}) }
Output:
func (*Logger) LogSync ¶
LogSync logs the Entry synchronously without any buffering. Because LogSync is slow and will block, it is intended primarily for debugging or critical errors. Prefer Log for most uses. TODO(jba): come up with a better name (LogNow?) or eliminate.
Example ¶
package main import ( "cloud.google.com/go/preview/logging" "golang.org/x/net/context" ) func main() { ctx := context.Background() client, err := logging.NewClient(ctx, "my-project") if err != nil { // TODO: Handle error. } lg := client.Logger("my-log") err = lg.LogSync(ctx, logging.Entry{Payload: "red alert"}) if err != nil { // TODO: Handle error. } }
Output:
func (*Logger) StandardLogger ¶
StandardLogger returns a *log.Logger for the provided severity.
This method is cheap. A single log.Logger is pre-allocated for each severity level in each Logger. Callers may mutate the returned log.Logger (for example by calling SetFlags or SetPrefix).
Example ¶
package main import ( "cloud.google.com/go/preview/logging" "golang.org/x/net/context" ) func main() { ctx := context.Background() client, err := logging.NewClient(ctx, "my-project") if err != nil { // TODO: Handle error. } lg := client.Logger("my-log") slg := lg.StandardLogger(logging.Info) slg.Println("an informative message") }
Output:
type LoggerOption ¶
type LoggerOption interface {
// contains filtered or unexported methods
}
A LoggerOption is a configuration option for a Logger.
func BufferedByteLimit ¶
func BufferedByteLimit(n int) LoggerOption
BufferedByteLimit is the 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. The default is DefaultBufferedByteLimit.
func CommonLabels ¶
func CommonLabels(m map[string]string) LoggerOption
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. If any of the log entries contains a (key, value) with the same key that is in CommonLabels, then the entry's (key, value) overrides the one in CommonLabels.
func CommonResource ¶
func CommonResource(r *mrpb.MonitoredResource) LoggerOption
CommonResource sets the monitored resource associated with all log entries written from a Logger. If not provided, a resource of type "global" is used. This value can be overridden by setting an Entry's Resource field.
func DelayThreshold ¶
func DelayThreshold(d time.Duration) LoggerOption
DelayThreshold is the maximum amount of time that an entry should remain buffered in memory before a call to the logging service is triggered. Larger values of DelayThreshold will generally result in fewer calls to the logging service, while increasing the risk that log entries will be lost if the process crashes. The default is DefaultDelayThreshold.
func EntryByteLimit ¶
func EntryByteLimit(n int) LoggerOption
EntryByteLimit is the maximum number of bytes of entries that will be sent in a single call to the logging service. This option limits the size of a single RPC payload, to account for network or service issues with large RPCs. If EntryByteLimit is smaller than EntryByteThreshold, the latter has no effect. The default is zero, meaning there is no limit.
func EntryByteThreshold ¶
func EntryByteThreshold(n int) LoggerOption
EntryByteThreshold is the maximum number of bytes of entries that will be buffered in memory before a call to the logging service is triggered. See EntryCountThreshold for a discussion of the tradeoffs involved in setting this option. The default is DefaultEntryByteThreshold.
func EntryCountThreshold ¶
func EntryCountThreshold(n int) LoggerOption
EntryCountThreshold is the maximum number of entries that will be buffered in memory before a call to the logging service is triggered. Larger values will generally result in fewer calls to the logging service, while increasing both memory consumption and the risk that log entries will be lost if the process crashes. The default is DefaultEntryCountThreshold.
type Severity ¶
type Severity int
Severity is the severity of the event described in a log entry. These guideline severity levels are ordered, with numerically smaller levels treated as less severe than numerically larger levels.
func ParseSeverity ¶
ParseSeverity returns the Severity whose name equals s, ignoring case. It returns Default if no Severity matches.
Example ¶
package main import ( "fmt" "cloud.google.com/go/preview/logging" ) func main() { sev := logging.ParseSeverity("ALERT") fmt.Println(sev) }
Output: Alert
Directories ¶
Path | Synopsis |
---|---|
testing
Package testing provides support for testing the logging client.
|
Package testing provides support for testing the logging client. |
Package logadmin contains a Stackdriver Logging client that can be used for reading logs and working with sinks, metrics and monitored resources.
|
Package logadmin contains a Stackdriver Logging client that can be used for reading logs and working with sinks, metrics and monitored resources. |