googlecloud

Documentation

Overview

The googlecloud package supports telemetry (tracing, metrics and logging) using Google Cloud services.

The googlecloud package supports telemetry (tracing, metrics and logging) using Google Cloud services.

Index

• Constants
• func EnableGoogleCloudTelemetry(options *GoogleCloudTelemetryOptions)
• func FlushMetrics(ctx context.Context) error
• type ActionTelemetry
  • func NewActionTelemetry() *ActionTelemetry
  • func (a *ActionTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)
• type AdjustingTraceExporter
  • func (e *AdjustingTraceExporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error
  • func (e *AdjustingTraceExporter) ForceFlush(ctx context.Context) error
  • func (e *AdjustingTraceExporter) Shutdown(ctx context.Context) error
• type EngagementTelemetry
  • func NewEngagementTelemetry() *EngagementTelemetry
  • func (e *EngagementTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)
• type FeatureTelemetry
  • func NewFeatureTelemetry() *FeatureTelemetry
  • func (f *FeatureTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)
• type GcpAuthConfig
  • func CredentialsFromEnvironment() (*GcpAuthConfig, error)
• type GcpPrincipal
  • func ResolveCurrentPrincipal() (*GcpPrincipal, error)
• type GenerateTelemetry
  • func NewGenerateTelemetry() *GenerateTelemetry
  • func (g *GenerateTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)
• type GoogleCloudTelemetryOptions
• type MetricCounter
  • func NewMetricCounter(name string, opts MetricCounterOptions) *MetricCounter
  • func (m *MetricCounter) Add(value int64, attributes map[string]interface{})
• type MetricCounterOptions
• type MetricHistogram
  • func NewMetricHistogram(name string, opts MetricHistogramOptions) *MetricHistogram
  • func (m *MetricHistogram) Record(value float64, attributes map[string]interface{})
• type MetricHistogramOptions
• type PathTelemetry
  • func NewPathTelemetry() *PathTelemetry
  • func (p *PathTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)
• type SharedDimensions
• type Telemetry

Constants

const (
	MaxLogContentLength = 128000
	MaxPathLength       = 4096
)

const MetadataKey = "metadata"

MetadataKey is the slog attribute key used for structured metadata

Functions

func EnableGoogleCloudTelemetry

func EnableGoogleCloudTelemetry(options *GoogleCloudTelemetryOptions)

EnableGoogleCloudTelemetry enables comprehensive telemetry export to Google Cloud Observability suite. This directly initializes telemetry without requiring plugin registration.

Example usage:

// Zero-config (auto-detects project ID)
googlecloud.EnableGoogleCloudTelemetry(nil)
g, err := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}))

// With configuration
googlecloud.EnableGoogleCloudTelemetry(&googlecloud.GoogleCloudTelemetryOptions{
	ProjectID:      "my-project",
	ForceDevExport: true,
})
g, err := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}))

func FlushMetrics

func FlushMetrics(ctx context.Context) error

FlushMetrics forces an immediate flush of all pending metrics to Google Cloud. This is useful for short-lived processes or when you want to ensure metrics are exported before continuing execution.

Types

type ActionTelemetry

type ActionTelemetry struct {
}

ActionTelemetry implements telemetry collection for action input/output logging

func NewActionTelemetry

func NewActionTelemetry() *ActionTelemetry

NewActionTelemetry creates a new action telemetry module

func (*ActionTelemetry) Tick

func (a *ActionTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)

Tick processes a span for action telemetry

type AdjustingTraceExporter

type AdjustingTraceExporter struct {
	// contains filtered or unexported fields
}

AdjustingTraceExporter combines PII filtering and telemetry processing

func (*AdjustingTraceExporter) ExportSpans

func (e *AdjustingTraceExporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error

func (*AdjustingTraceExporter) ForceFlush

func (e *AdjustingTraceExporter) ForceFlush(ctx context.Context) error

func (*AdjustingTraceExporter) Shutdown

func (e *AdjustingTraceExporter) Shutdown(ctx context.Context) error

type EngagementTelemetry

type EngagementTelemetry struct {
	// contains filtered or unexported fields
}

EngagementTelemetry implements telemetry collection for user engagement (feedback/acceptance)

func NewEngagementTelemetry

func NewEngagementTelemetry() *EngagementTelemetry

NewEngagementTelemetry creates a new engagement telemetry module with required metrics

func (*EngagementTelemetry) Tick

func (e *EngagementTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)

Tick processes a span for engagement telemetry

type FeatureTelemetry

type FeatureTelemetry struct {
	// contains filtered or unexported fields
}

FeatureTelemetry implements telemetry collection for top-level feature requests

func NewFeatureTelemetry

func NewFeatureTelemetry() *FeatureTelemetry

NewFeatureTelemetry creates a new feature telemetry module with required metrics

func (*FeatureTelemetry) Tick

func (f *FeatureTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)

Tick processes a span for feature telemetry

type GcpAuthConfig

type GcpAuthConfig struct {
	ProjectID   string
	Credentials *google.Credentials
}

GcpAuthConfig represents authentication configuration for GCP

func CredentialsFromEnvironment

func CredentialsFromEnvironment() (*GcpAuthConfig, error)

CredentialsFromEnvironment allows Google Cloud credentials to be passed in "raw" as an environment variable. This is helpful in environments where the developer has limited ability to configure their compute environment, but does have the ability to set environment variables.

This is different from the GOOGLE_APPLICATION_CREDENTIALS used by ADC, which represents a path to a credential file on disk. In *most* cases, even for 3rd party cloud providers, developers *should* attempt to use ADC, which searches for credential files in standard locations, before using this method.

See also: https://cloud.google.com/docs/authentication/provide-credentials-adc

type GcpPrincipal

type GcpPrincipal struct {
	ProjectID           string `json:"project_id,omitempty"`
	ServiceAccountEmail string `json:"service_account_email,omitempty"`
}

GcpPrincipal represents the current GCP principal information

func ResolveCurrentPrincipal

func ResolveCurrentPrincipal() (*GcpPrincipal, error)

ResolveCurrentPrincipal resolves the currently configured principal, either from the Genkit specific GCLOUD_SERVICE_ACCOUNT_CREDS environment variable, or from ADC.

Since the Google Cloud Telemetry Exporter will discover credentials on its own, we don't immediately have access to the current principal. This method can be handy to get access to the current credential for logging debugging information or other purposes.

type GenerateTelemetry

type GenerateTelemetry struct {
	// contains filtered or unexported fields
}

GenerateTelemetry implements telemetry collection for model generate actions

func NewGenerateTelemetry

func NewGenerateTelemetry() *GenerateTelemetry

NewGenerateTelemetry creates a new generate telemetry module with all required metrics

func (*GenerateTelemetry) Tick

func (g *GenerateTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)

Tick processes a span for generate telemetry

type GoogleCloudTelemetryOptions

type GoogleCloudTelemetryOptions struct {
	// ProjectID is the Google Cloud project ID.
	// If empty, will be auto-detected from environment.
	ProjectID string

	// Credentials for authenticating with Google Cloud.
	// If nil, uses Application Default Credentials (ADC).
	// Primarily intended for use in environments outside of GCP.
	// On GCP, credentials will typically be inferred from the environment via ADC.
	Credentials *google.Credentials

	// Sampler controls trace sampling. If nil, uses AlwaysOnSampler.
	// Examples: AlwaysOnSampler, AlwaysOffSampler, TraceIdRatioBasedSampler
	Sampler sdktrace.Sampler

	// MetricExportIntervalMillis controls metrics export frequency.
	// Google Cloud requires minimum 5000ms. Defaults to 5000 (dev) or 300000 (prod).
	MetricExportIntervalMillis *int

	// MetricExportTimeoutMillis controls metrics export timeout.
	// Defaults to match MetricExportIntervalMillis.
	MetricExportTimeoutMillis *int

	// DisableMetrics disables metric export to Google Cloud.
	// Traces and logs may still be exported. Defaults to false.
	DisableMetrics bool

	// DisableTraces disables trace export to Google Cloud.
	// Metrics and logs may still be exported. Defaults to false.
	DisableTraces bool

	// DisableLoggingInputAndOutput disables input/output logging.
	// Defaults to false (input/output logging enabled).
	DisableLoggingInputAndOutput bool

	// ForceDevExport forces telemetry export even in development environment.
	// Defaults to false (only exports in production unless forced).
	ForceDevExport bool
}

GoogleCloudTelemetryOptions provides comprehensive configuration for Google Cloud telemetry. Matches the JavaScript Google Cloud plugin options for full compatibility.

Environment Variables: - GENKIT_ENV: Set to "dev" to disable export unless ForceExport is true - GOOGLE_CLOUD_PROJECT: Auto-detected project ID if ProjectID is not set

type MetricCounter

type MetricCounter struct {
	// contains filtered or unexported fields
}

MetricCounter wraps OpenTelemetry counter with Genkit conventions

func NewMetricCounter

func NewMetricCounter(name string, opts MetricCounterOptions) *MetricCounter

NewMetricCounter creates a new counter metric with the given name and options

func (*MetricCounter) Add

func (m *MetricCounter) Add(value int64, attributes map[string]interface{})

Add records a value to the counter with the given attributes

type MetricCounterOptions

type MetricCounterOptions struct {
	Description string
	Unit        string
}

MetricCounterOptions holds configuration for a counter metric

type MetricHistogram

type MetricHistogram struct {
	// contains filtered or unexported fields
}

MetricHistogram wraps OpenTelemetry histogram with Genkit conventions

func NewMetricHistogram

func NewMetricHistogram(name string, opts MetricHistogramOptions) *MetricHistogram

NewMetricHistogram creates a new histogram metric with the given name and options

func (*MetricHistogram) Record

func (m *MetricHistogram) Record(value float64, attributes map[string]interface{})

Record records a value to the histogram with the given attributes

type MetricHistogramOptions

type MetricHistogramOptions struct {
	Description string
	Unit        string
}

MetricHistogramOptions holds configuration for a histogram metric

type PathTelemetry

type PathTelemetry struct {
	// contains filtered or unexported fields
}

PathTelemetry implements telemetry collection for error/failure path tracking

func NewPathTelemetry

func NewPathTelemetry() *PathTelemetry

NewPathTelemetry creates a new path telemetry module with required metrics

func (*PathTelemetry) Tick

func (p *PathTelemetry) Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)

Tick processes a span for path telemetry

type SharedDimensions

type SharedDimensions struct {
	FeatureName   string
	Path          string
	Status        string
	Source        string
	SourceVersion string
}

SharedDimensions contains common metric dimensions used across telemetry modules

type Telemetry

type Telemetry interface {
	Tick(span sdktrace.ReadOnlySpan, logInputOutput bool, projectID string)
}

Telemetry interface that all telemetry modules implement