or run

tessl search

Version

Workspace: tessl
Visibility: Public
Created: 6 days ago
Last updated: about 16 hours ago
Describes: pkg:golang/cloud.google.com/go/logging@v1.13.1

docs

architecture.md client-logger.md constants.md errors.md http-request.md index.md logadmin.md logger-config.md payloads.md severity.md standard-logger.md tracing.md writing-logs.md

tile.json

tessl/golang-cloud-google-com--go--logging

tessl install tessl/golang-cloud-google-com--go--logging@1.13.0

Cloud Logging client library for Go that enables writing log entries to Google Cloud Logging service with buffered asynchronous and synchronous logging capabilities.

Constants and Defaults

This document describes all constants defined in the Cloud Logging library, including OAuth scopes, default configuration values, and source location population options.

OAuth Scope Constants

const (
    ReadScope  = "https://www.googleapis.com/auth/logging.read"
    WriteScope = "https://www.googleapis.com/auth/logging.write"
    AdminScope = "https://www.googleapis.com/auth/logging.admin"
)

OAuth 2.0 scopes for accessing Cloud Logging APIs.

ReadScope

const ReadScope = "https://www.googleapis.com/auth/logging.read"

Scope for reading from the logging service. Used by the logadmin package when reading logs. Allows:

Reading log entries
Listing logs
Reading sinks and metrics (read-only)
Reading monitored resource descriptors

Example:

import (
    "google.golang.org/api/option"
    "cloud.google.com/go/logging"
)

client, err := logging.NewClient(ctx, "my-project",
    option.WithScopes(logging.ReadScope),
)

WriteScope

const WriteScope = "https://www.googleapis.com/auth/logging.write"

Scope for writing to the logging service. This is the default scope for logging.NewClient. Allows:

Writing log entries
No read or admin operations

Example:

// WriteScope is the default, so this is automatic
client, err := logging.NewClient(ctx, "my-project")

// Explicitly specify if needed
client, err := logging.NewClient(ctx, "my-project",
    option.WithScopes(logging.WriteScope),
)

AdminScope

const AdminScope = "https://www.googleapis.com/auth/logging.admin"

Scope for administrative actions on the logging service. This is the default scope for logadmin.NewClient. Allows:

All read operations
All write operations
Creating, updating, and deleting sinks
Creating, updating, and deleting metrics
Deleting logs

Example:

import "cloud.google.com/go/logging/logadmin"

// AdminScope is the default for logadmin
client, err := logadmin.NewClient(ctx, "my-project")

// Explicitly specify if needed
client, err := logadmin.NewClient(ctx, "my-project",
    option.WithScopes(logging.AdminScope),
)

Default Configuration Constants

const (
    DefaultDelayThreshold      = time.Second
    DefaultEntryCountThreshold = 1000
    DefaultEntryByteThreshold  = 8388608      // 8 MiB
    DefaultBundleByteLimit     = 9437184      // 9.5 MiB
    DefaultBufferedByteLimit   = 1073741824   // 1 GiB
)

Default values for Logger buffering and batching configuration.

DefaultDelayThreshold

const DefaultDelayThreshold = time.Second

Default value for the DelayThreshold LoggerOption. Maximum time a log entry remains buffered before triggering a write to Cloud Logging.

Value: 1 second

Usage:

// Use default (1 second)
logger := client.Logger("my-log")

// Override with custom value
logger := client.Logger("my-log",
    logging.DelayThreshold(500*time.Millisecond), // 500ms
)

DefaultEntryCountThreshold

const DefaultEntryCountThreshold = 1000

Default value for the EntryCountThreshold LoggerOption. Maximum number of entries buffered before triggering a write to Cloud Logging.

Value: 1000 entries

Usage:

// Use default (1000 entries)
logger := client.Logger("my-log")

// Override with custom value
logger := client.Logger("my-log",
    logging.EntryCountThreshold(500), // Flush at 500 entries
)

DefaultEntryByteThreshold

const DefaultEntryByteThreshold = 1 << 23  // 8 MiB

Default value for the EntryByteThreshold LoggerOption. Maximum bytes of entries buffered before triggering a write to Cloud Logging.

Value: 8 MiB (8,388,608 bytes)

Usage:

// Use default (8 MiB)
logger := client.Logger("my-log")

// Override with custom value
logger := client.Logger("my-log",
    logging.EntryByteThreshold(4<<20), // 4 MiB
)

DefaultBundleByteLimit

const DefaultBundleByteLimit = 9437184  // 9.5 MiB

Default value for the BundleByteLimit LoggerOption. Maximum bytes sent in a single call to the Cloud Logging service. This is close to the 10 MiB gRPC message size limit.

Value: 9.5 MiB (9,437,184 bytes)

Usage:

// Use default (9.5 MiB)
logger := client.Logger("my-log")

// Override with custom value (not recommended unless you have specific needs)
logger := client.Logger("my-log",
    logging.EntryByteLimit(5<<20), // 5 MiB
)

DefaultBufferedByteLimit

const DefaultBufferedByteLimit = 1 << 30  // 1 GiB

Default value for the BufferedByteLimit LoggerOption. Maximum memory (in bytes) a Logger will use for buffering entries before returning ErrOverflow.

Value: 1 GiB (1,073,741,824 bytes)

Usage:

// Use default (1 GiB)
logger := client.Logger("my-log")

// Override with custom value
logger := client.Logger("my-log",
    logging.BufferedByteLimit(512<<20), // 512 MiB
)

Project ID Detection Constant

const DetectProjectID = "*detect-project-id*"

Sentinel value that instructs NewClient to auto-detect the project ID from the environment. NewClient will use the project ID from:

The provided credentials
Default credentials (Application Default Credentials)

Usage:

// Auto-detect project ID
client, err := logging.NewClient(ctx, logging.DetectProjectID)

// Equivalent to explicitly providing the project ID
client, err := logging.NewClient(ctx, "my-project")

Auto-detection sources:

GCE metadata server
GAE environment
GKE environment
Cloud Run environment
Service account credentials
User credentials with project binding

Source Location Population Constants

const (
    DoNotPopulateSourceLocation           = 0
    PopulateSourceLocationForDebugEntries = 1
    AlwaysPopulateSourceLocation          = 2
)

Constants for controlling automatic population of the SourceLocation field in log entries.

DoNotPopulateSourceLocation

const DoNotPopulateSourceLocation = 0

Default value. Disables automatic source location population. The SourceLocation field will only be set if explicitly provided in the Entry.

Usage:

// Default behavior - no source location
logger := client.Logger("my-log")

// Explicitly specify (same as default)
logger := client.Logger("my-log",
    logging.SourceLocationPopulation(logging.DoNotPopulateSourceLocation),
)

PopulateSourceLocationForDebugEntries

const PopulateSourceLocationForDebugEntries = 1

Populates the SourceLocation field only for log entries with Debug severity. The source location includes:

Source file path
Line number
Function name

Performance impact: Moderate. Only affects Debug-level logs.

Usage:

logger := client.Logger("my-log",
    logging.SourceLocationPopulation(logging.PopulateSourceLocationForDebugEntries),
)

// This entry WILL have source location
logger.Log(logging.Entry{
    Payload:  "debug information",
    Severity: logging.Debug,
})

// This entry will NOT have source location
logger.Log(logging.Entry{
    Payload:  "info message",
    Severity: logging.Info,
})

AlwaysPopulateSourceLocation

const AlwaysPopulateSourceLocation = 2

Always populates the SourceLocation field for all log entries, regardless of severity.

Performance impact: Significant. Can decrease performance by a factor of 2 or more, as it requires runtime stack inspection for every log call.

Usage:

logger := client.Logger("my-log",
    logging.SourceLocationPopulation(logging.AlwaysPopulateSourceLocation),
)

// ALL entries will have source location
logger.Log(logging.Entry{
    Payload:  "any message",
    Severity: logging.Info,
})

Source location includes:

type LogEntrySourceLocation struct {
    File     string  // Source file: "main.go"
    Line     int64   // Line number: 42
    Function string  // Full function name: "main.handleRequest"
}

Buffering Behavior

The default buffering thresholds work together to control when log entries are sent:

+-------------------+---------------------------+
| Threshold         | Default Value             |
+-------------------+---------------------------+
| Time              | 1 second                  |
| Entry Count       | 1000 entries              |
| Buffered Bytes    | 8 MiB                     |
+-------------------+---------------------------+
| Bundle Size Limit | 9.5 MiB per RPC           |
| Buffer Memory Max | 1 GiB (before overflow)   |
+-------------------+---------------------------+

Flushing behavior:

Entries are sent when any threshold is met:

1 second has elapsed since the last flush
OR 1000 entries are buffered
OR 8 MiB of entries are buffered

Example scenarios:

// High-volume logging: likely flushes on entry count or byte threshold
for i := 0; i < 10000; i++ {
    logger.Log(logging.Entry{Payload: "message"})
}
// Flushes when 1000 entries or 8 MiB buffered

// Low-volume logging: likely flushes on time threshold
logger.Log(logging.Entry{Payload: "occasional message"})
// Flushes after 1 second

Complete Example

package main

import (
    "context"
    "log"
    "time"

    "cloud.google.com/go/logging"
    "google.golang.org/api/option"
)

func main() {
    ctx := context.Background()

    // Auto-detect project ID
    client, err := logging.NewClient(ctx, logging.DetectProjectID)
    if err != nil {
        log.Fatalf("failed to create client: %v", err)
    }
    defer client.Close()

    // Logger with custom thresholds
    logger := client.Logger("custom-log",
        // Flush more aggressively than defaults
        logging.DelayThreshold(500*time.Millisecond),           // vs 1 second default
        logging.EntryCountThreshold(500),                       // vs 1000 default
        logging.EntryByteThreshold(4<<20),                      // 4 MiB vs 8 MiB default

        // Increase buffer to prevent overflow
        logging.BufferedByteLimit(2<<30),                       // 2 GiB vs 1 GiB default

        // Enable source location for debug logs
        logging.SourceLocationPopulation(logging.PopulateSourceLocationForDebugEntries),
    )

    // Log with source location (Debug severity)
    logger.Log(logging.Entry{
        Payload:  "debug with source location",
        Severity: logging.Debug,
    })

    // Log without source location (Info severity)
    logger.Log(logging.Entry{
        Payload:  "info without source location",
        Severity: logging.Info,
    })

    logger.Flush()
}

Scope Comparison

Scope	Read Logs	Write Logs	Read Sinks/Metrics	Manage Sinks/Metrics	Delete Logs
ReadScope	✓	✗	✓	✗	✗
WriteScope	✗	✓	✗	✗	✗
AdminScope	✓	✓	✓	✓	✓

Best Practices

Scope Selection

// For applications that only write logs
client, _ := logging.NewClient(ctx, "my-project")
// Uses WriteScope by default

// For applications that read and write logs
client, _ := logging.NewClient(ctx, "my-project",
    option.WithScopes(logging.AdminScope),
)

// For read-only log analysis tools
client, _ := logadmin.NewClient(ctx, "my-project",
    option.WithScopes(logging.ReadScope),
)

Threshold Tuning

// High-volume, high-throughput
logger := client.Logger("high-volume",
    logging.DelayThreshold(100*time.Millisecond),  // Flush quickly
    logging.EntryCountThreshold(10000),            // Large batches
    logging.ConcurrentWriteLimit(10),              // More concurrent RPCs
)

// Low-volume, latency-sensitive
logger := client.Logger("low-volume",
    logging.DelayThreshold(5*time.Second),         // Wait longer
    logging.EntryCountThreshold(100),              // Small batches
)

// Memory-constrained environment
logger := client.Logger("constrained",
    logging.BufferedByteLimit(64<<20),             // 64 MiB max buffer
    logging.EntryByteThreshold(2<<20),             // Flush at 2 MiB
)

Source Location

// Development/debugging - always populate
logger := client.Logger("dev-log",
    logging.SourceLocationPopulation(logging.AlwaysPopulateSourceLocation),
)

// Production - only for debug logs
logger := client.Logger("prod-log",
    logging.SourceLocationPopulation(logging.PopulateSourceLocationForDebugEntries),
)

// Production high-performance - disabled
logger := client.Logger("perf-log",
    logging.SourceLocationPopulation(logging.DoNotPopulateSourceLocation),
)

Version

tessl/golang-cloud-google-com--go--logging

constants.mddocs/

Constants and Defaults

OAuth Scope Constants

ReadScope

WriteScope

AdminScope

Default Configuration Constants

DefaultDelayThreshold

DefaultEntryCountThreshold

DefaultEntryByteThreshold

DefaultBundleByteLimit

DefaultBufferedByteLimit

Project ID Detection Constant

Source Location Population Constants

DoNotPopulateSourceLocation

PopulateSourceLocationForDebugEntries

AlwaysPopulateSourceLocation

Buffering Behavior

Complete Example

Scope Comparison

Best Practices

Scope Selection

Threshold Tuning

Source Location

Related Documentation

Version

tessl/golang-cloud-google-com--go--logging

constants.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Constants and Defaults

OAuth Scope Constants

ReadScope

WriteScope

AdminScope

Default Configuration Constants

DefaultDelayThreshold

DefaultEntryCountThreshold

DefaultEntryByteThreshold

DefaultBundleByteLimit

DefaultBufferedByteLimit

Project ID Detection Constant

Source Location Population Constants

DoNotPopulateSourceLocation

PopulateSourceLocationForDebugEntries

AlwaysPopulateSourceLocation

Buffering Behavior

Complete Example

Scope Comparison

Best Practices

Scope Selection

Threshold Tuning

Source Location

Related Documentation

constants.mddocs/