or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/cloud.google.com/go/logging@v1.13.1

docs

architecture.mdclient-logger.mdconstants.mderrors.mdhttp-request.mdindex.mdlogadmin.mdlogger-config.mdpayloads.mdseverity.mdstandard-logger.mdtracing.mdwriting-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.

severity.mddocs/

Severity Levels

This document describes the severity levels available for log entries and how to use them.

Severity Type

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.

Severity Constants

const (
    Default   Severity  // Log entry has no assigned severity level
    Debug     Severity  // Debug or trace information
    Info      Severity  // Routine information, such as ongoing status or performance
    Notice    Severity  // Normal but significant events, such as start up, shut down, or configuration
    Warning   Severity  // Events that might cause problems
    Error     Severity  // Events that are likely to cause problems
    Critical  Severity  // Events that cause more severe problems or brief outages
    Alert     Severity  // A person must take an action immediately
    Emergency Severity  // One or more systems are unusable
)

Using Severity Levels

// Default severity (no severity specified)
logger.Log(logging.Entry{
    Payload: "routine message",
})

// Debug - diagnostic information
logger.Log(logging.Entry{
    Payload:  "variable value: x=42",
    Severity: logging.Debug,
})

// Info - routine information
logger.Log(logging.Entry{
    Payload:  "request processed successfully",
    Severity: logging.Info,
})

// Notice - normal but significant events
logger.Log(logging.Entry{
    Payload:  "service started",
    Severity: logging.Notice,
})

// Warning - potential problems
logger.Log(logging.Entry{
    Payload:  "disk space running low",
    Severity: logging.Warning,
})

// Error - errors that need attention
logger.Log(logging.Entry{
    Payload:  "failed to connect to database",
    Severity: logging.Error,
})

// Critical - severe problems
logger.Log(logging.Entry{
    Payload:  "database connection pool exhausted",
    Severity: logging.Critical,
})

// Alert - immediate action required
logger.Log(logging.Entry{
    Payload:  "service is down",
    Severity: logging.Alert,
})

// Emergency - system unusable
logger.Log(logging.Entry{
    Payload:  "complete system failure",
    Severity: logging.Emergency,
})

Parsing Severity from String

func ParseSeverity(s string) Severity

ParseSeverity returns the Severity whose name equals s, ignoring case. It returns Default if no Severity matches.

Parameters:

  • s - String representation of severity (case-insensitive)

Returns:

  • Severity - Parsed severity value, or Default if not found

Example:

sev1 := logging.ParseSeverity("ERROR")    // Returns logging.Error
sev2 := logging.ParseSeverity("warning")  // Returns logging.Warning
sev3 := logging.ParseSeverity("Info")     // Returns logging.Info
sev4 := logging.ParseSeverity("unknown")  // Returns logging.Default

logger.Log(logging.Entry{
    Payload:  "message",
    Severity: sev1,
})

Converting Severity to String

func (v Severity) String() string

String converts a severity level to a string.

Returns:

  • string - String representation of the severity

Example:

sev := logging.Error
sevStr := sev.String()  // Returns "ERROR"

fmt.Printf("Logging at %s level\n", sevStr)

Unmarshaling Severity from JSON

func (v *Severity) UnmarshalJSON(data []byte) error

UnmarshalJSON turns a string representation of severity into the type Severity.

Parameters:

  • data - JSON data containing severity string

Returns:

  • error - Error if unmarshaling fails

Example:

import "encoding/json"

type LogConfig struct {
    MinSeverity logging.Severity `json:"min_severity"`
    MaxEntries  int               `json:"max_entries"`
}

jsonData := []byte(`{"min_severity": "WARNING", "max_entries": 1000}`)

var config LogConfig
err := json.Unmarshal(jsonData, &config)
if err != nil {
    // Handle error
}

// config.MinSeverity is now logging.Warning

Severity-Based Filtering

Use severity levels to control which logs are processed:

func shouldLog(entry logging.Entry, minSeverity logging.Severity) bool {
    return entry.Severity >= minSeverity
}

// Only log warnings and above
minSeverity := logging.Warning

entry := logging.Entry{
    Payload:  "some message",
    Severity: logging.Info,
}

if shouldLog(entry, minSeverity) {
    logger.Log(entry)
}

Severity Guidelines

Default: Use for logs that don't fit other categories or when severity is not important.

Debug: Use for detailed diagnostic information useful during development and troubleshooting. Should be disabled in production for performance.

Info: Use for informational messages about normal operations (requests processed, tasks completed, etc.).

Notice: Use for significant but normal events (service started/stopped, configuration changes, scheduled tasks).

Warning: Use for potentially harmful situations that don't prevent operation (deprecated API usage, high resource usage, retryable errors).

Error: Use for error events that may still allow the application to continue (failed requests, database errors, invalid input).

Critical: Use for critical conditions that should be investigated immediately (system component failures, data corruption).

Alert: Use for conditions requiring immediate human action (service outage, security breach).

Emergency: Use when the system is unusable (complete failure, catastrophic errors).

Complete Example

package main

import (
    "context"
    "log"

    "cloud.google.com/go/logging"
)

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

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

    logger := client.Logger("app-log")

    // Log at different severity levels
    logger.Log(logging.Entry{
        Payload:  "Application starting",
        Severity: logging.Notice,
    })

    logger.Log(logging.Entry{
        Payload:  "Configuration loaded successfully",
        Severity: logging.Info,
    })

    // Parse severity from string
    configuredLevel := "WARNING"
    severity := logging.ParseSeverity(configuredLevel)

    logger.Log(logging.Entry{
        Payload:  "This is a warning",
        Severity: severity,
    })

    // Convert severity to string for logging
    currentSeverity := logging.Error
    log.Printf("Current severity: %s", currentSeverity.String())

    logger.Flush()
}