interop library

A library that allows framework developers to interoperate with Google Cloud Logging.

How Log Correlation Works

Log correlation associates individual application logs with the HTTP request that triggered them, allowing GCP Cloud Logging to group them in the log viewer. To achieve this without requiring application developers to manually pass logging context through their call stack, this package uses Dart Zone variables:

  1. Framework Middleware: An HTTP framework or middleware (such as package:google_cloud_shelf) extracts the W3C traceparent header from an incoming HTTP request and determines the Google Cloud Project ID.
  2. Zone Forking: The middleware forks a new Zone containing these values keyed by googleCloudProjectIdZoneVariable and traceparentHeaderValueZoneVariable.
  3. Log Resolution: When application code logs a message via package:google_cloud_logging, the logger implicitly reads these values from the current zone and formats them into GCP structured logging fields (logging.googleapis.com/trace and logging.googleapis.com/spanId).

For more details on structured logging and Shelf request correlation, see package:google_cloud_shelf documentation.

Tip

Application developers should not use this library, instead use package:google_cloud_logging/google_cloud_logging.dart.

Constants

googleCloudProjectIdZoneVariable → const String
The unique ID String for the current project when run on Google Cloud.
traceparentHeaderValueZoneVariable → const String
The String value for the traceparent W3C HTTP header.

Functions

createStructuredLog(Object message, LogSeverity severity, {Map<String, Object?>? payload, String? traceparent, Zone? zone, StackTrace? stackTrace, String? projectId}) → String
Formats a log entry for Google Cloud structured logging on stdout.