Socket
Socket
Sign inDemoInstall

cloud.google.com/go/logging

Package Overview
Dependencies
28
Maintainers
0
Alerts
File Explorer

Install Socket

Protect your apps from supply chain attacks

Install

cloud.google.com/go/logging

Package logging contains a Cloud 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. Use a Client to interact with the Cloud Logging API. For most use cases, you'll want to add log entries to a buffer to be periodically flushed (automatically and asynchronously) to the Cloud Logging service. You should call Client.Close before your program exits to flush any buffered log entries to the Cloud Logging service. 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 normal use. For cases when runtime environment supports out-of-process log ingestion, like logging agent, you can opt-in to write log entries to io.Writer instead of ingesting them to Cloud Logging service. Usually, you will use os.Stdout or os.Stderr as writers because Google Cloud logging agents are configured to capture logs from standard output. The entries will be Jsonified and wrote as one line strings following the structured logging format. See https://cloud.google.com/logging/docs/structured-logging#special-payload-fields for the format description. To instruct Logger to redirect log entries add RedirectAsJSON() LoggerOption`s. An entry payload can be a string, as in the examples above. It can also be any value that can be marshaled to a JSON object, like a map[string]interface{} or a struct: If you have a []byte of JSON, wrap it in json.RawMessage: If you have proto.Message and want to send it as a protobuf payload, marshal it to anypb.Any: You may want use a standard log.Logger in your program. An Entry may have one of a number of severity levels associated with it. You can view Cloud logs for projects at https://console.cloud.google.com/logs/viewer. Use the dropdown at the top left. When running from a Google Cloud Platform VM, select "GCE VM Instance". Otherwise, select "Google Project" and then the project ID. Logs for organizations, folders and billing accounts can be viewed on the command line with the "gcloud logging read" command. To group all the log entries written during a single HTTP request, create two Loggers, a "parent" and a "child," with different log IDs. Both should be in the same project, and have the same MonitoredResource type and labels. - A child entry's timestamp must be within the time interval covered by the parent request. (i.e., before the parent.Timestamp and after the parent.Timestamp - parent.HTTPRequest.Latency. This assumes the parent.Timestamp marks the end of the request.) - The trace field must be populated in all of the entries and match exactly. You should observe the child log entries grouped under the parent on the console. The parent entry will not inherit the severity of its children; you must update the parent severity yourself.

    v1.9.0

Version published
Maintainers
0

Readme

## Cloud Logging [![Go Reference](https://pkg.go.dev/badge/cloud.google.com/go/logging.svg)](https://pkg.go.dev/cloud.google.com/go/logging)

- [About Cloud Logging](https://cloud.google.com/logging/)
- [API documentation](https://cloud.google.com/logging/docs)
- [Go client documentation](https://pkg.go.dev/cloud.google.com/go/logging)
- [Complete sample programs](https://github.com/GoogleCloudPlatform/golang-samples/tree/main/logging)

For an interactive tutorial on using the client library in a Go application, click [Guide Me](https://console.cloud.google.com/?walkthrough_id=logging__logging-go).
### Example Usage

First create a `logging.Client` to use throughout your application:
[snip]:# (logging-1)

```go
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)

```go
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)

```go
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)

```go
err = client.Close()
if err != nil {
   // TODO: Handle error.
}
```

### Logger configuration options

Creating a Logger using `logging.Logger` accept configuration [LoggerOption](loggeroption.go#L25) 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](https://cloud.google.com/logging/docs/reference/v2/rest/v2/entries/write#body.request_body.FIELDS.partial_success) 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](https://cloud.google.com/logging/docs/structured-logging#special-payload-fields) 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. |

FAQs

Last updated on 12 Dec 2023

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc