Skip to content

Latest commit

 

History

History
155 lines (112 loc) · 6.69 KB

std-lib-integration.rst

File metadata and controls

155 lines (112 loc) · 6.69 KB
Raw

Integration with logging Standard Library

We recommend that you use google-cloud-logging to integrate with the Python logging standard library. This way, you can write logs using Python standards, and still have your logs appear in Google Cloud Logging.

Automatic Configuration

To integrate google-cloud-logging with the standard logging module, call ~google.cloud.logging_v2.client.Client.setup_logging on a ~google.cloud.logging_v2.client.Client instance.

../samples/snippets/handler.py

This ~google.cloud.logging_v2.client.Client.setup_logging function chooses the best configurations for the environment your code is running on. For more information, see the Google Cloud Logging documentation.

Manual Handler Configuration

Automatic Configuration automatically determines the appropriate handler for the environment. To specify the handler yourself, construct an instance manually and pass it in as an argument to ~google.cloud.logging_v2.handlers.setup_logging:

../samples/snippets/usage_guide.py

There are two supported handler classes to choose from:

  • ~google.cloud.logging_v2.handlers.handlers.CloudLoggingHandler:
    • Sends logs directly to Cloud Logging over the network (gRPC or HTTP</grpc-vs-http>)
    • Logs are transmitted according to a Transport <Transports> class
    • This is the default handler on most environments, including local development
  • ~google.cloud.logging_v2.handlers.structured_log.StructuredLogHandler:
    • Outputs logs as structured JSON to standard out, to be read and parsed by a GCP logging agent
    • This is the default handler on Kubernetes Engine, Cloud Functions and Cloud Run

Handler classes can also be specified via dictConfig:

../samples/snippets/usage_guide.py

Note that since ~google.cloud.logging_v2.handlers.handlers.CloudLoggingHandler requires an already initialized ~google.cloud.logging_v2.client.Client, you must initialize a client and include it in the dictConfig entry for a CloudLoggingHandler.

Standard Library

After you setup the Google Cloud Logging library with the Python logging standard library, you can send logs with the standard logging library as you normally would:

../samples/snippets/handler.py

For more information on using the Python logging standard library, see the logging documentation

Logging JSON Payloads

Although the Python logging standard library expects all logs to be strings, Google Cloud Logging allows JSON payload data.

To write JSON logs using the standard library integration, do one of the following:

  1. Use the json_fields extra argument:

../samples/snippets/usage_guide.py

  1. Log a JSON-parsable string:

../samples/snippets/usage_guide.py

Automatic Metadata Detection

The Google Cloud Logging library attempts to detect and attach additional LogEntry fields . The following fields are currently supported:

  • labels
  • trace*
  • span_id*
  • trace_sampled*
  • http_request*
  • source_location
  • resource
  • json_fields<JSON>

Note

Fields marked with "*" require a supported Python web framework </web-framework-integration>.

Manual Metadata Using the extra Argument

The Python logging standard library accepts an "extra" argument when writing logs. You can use this argument to populate LogRecord objects with user-defined key-value pairs. Google Cloud Logging uses the extra field as a way to pass in additional metadata to populate LogEntry fields.

../samples/snippets/usage_guide.py

All of the LogEntry fields that can be autodetected<Autodetection> can also be set manually through the extra argument. Fields sent explicitly through the extra argument override any automatically detected<Autodetection> fields.

CloudLoggingHandler Transports

Transport</transport> classes define how the ~google.cloud.logging_v2.handlers.handlers.CloudLoggingHandler transports logs over the network to Google Cloud. There are two Transport implementations (defined as subclasses of transports.base.Transport <google.cloud.logging_v2.handlers.transports.base.Transport>):

  • ~google.cloud.logging_v2.handlers.transports.background_thread.BackgroundThreadTransport:
    • sends logs in batches, using a background thread
    • the default Transport class
  • ~google.cloud.logging_v2.handlers.transports.sync.SyncTransport:
    • sends each log synchronously in a single API call

You can set a Transport class by passing it as an argument when initializing CloudLoggingHandler manually.<manual handler>

You can use both transport options over gRPC or HTTP</grpc-vs-http>.

Note

~google.cloud.logging_v2.handlers.structured_log.StructuredLogHandler prints logs as formatted JSON to standard output, and does not use a Transport class.