Sentry logger integration

Sentry error reporting integration for Piko's logger, registers a slog.Handler that ships error-level events to Sentry, plus a Sentry OpenTelemetry span processor and propagator for distributed-trace correlation.

Overview

Importing the package self-registers Sentry with Piko's logger-integration registry. The framework then looks the integration up by name (sentry), so the core logger and the Piko bootstrap stay unaware of the Sentry SDK. You enable it one of two ways. Call Enable(Config{...}) from your func main, or add an integration entry to piko.yaml. Either path triggers the SDK initialisation. Enable is idempotent, so calling it more than once does nothing after the first call.

The package provides two capabilities from one import. The first is a Sentry-backed slog handler that ships error events and structured log entries to the global logger state. The second is the OtelIntegration implementation. It hands the OTEL pipeline a Sentry span processor and propagator, so distributed traces stay correlated between Sentry's transaction view and the rest of your tracing stack.

The handler and the OTEL components attach through different paths. Enable(Config{...}) and the piko.yaml entry both add the slog handler. The OTEL span processor and propagator attach only through the piko.yaml integration entry. The logger collects them during its own setup from the config integrations marked enabled: true, so trace correlation needs the config path described below.

Through the public Config, EnableTracing is true, AddSource is true, and SendDefaultPII is false. The code path leaves the event and log levels unset, so the Sentry slog handler applies its own defaults. Error and fatal records become Sentry events. Debug, info, warn, error, and fatal records become Sentry log entries. To set explicit levels, ignore patterns, or PII behaviour, use the piko.yaml path described below.

Initialisation runs a separate SDK client. If init fails, the integration logs the error and keeps the handler out of the chain, so startup does not abort. All operations are safe for concurrent use.

A shutdown hook flushes pending events for you. It honours Piko's shutdown deadline instead of waiting a fixed time. The flush budget is the shutdown context's remaining time, capped at 30 seconds, and falls back to 2 seconds when the context carries no deadline. Graceful shutdown does not lose or stall events.

This integration is pure Go with no build tags or CGO. It behaves the same in interpreted dev mode (dev-i) and in compiled builds.

Requirements

  • A Sentry project with a DSN. Find the DSN under Project Settings -> Client Keys (DSN).
  • Network egress to your Sentry instance (*.ingest.sentry.io for SaaS, your own host for self-hosted).
  • Importing the package pulls in the getsentry/sentry-go module transitively.

Configuration

import (
    "os"

    "piko.sh/piko/wdk/logger/logger_integration_sentry"
)

logger_integration_sentry.Enable(logger_integration_sentry.Config{
    DSN:              os.Getenv("SENTRY_DSN"), // required
    Environment:      "production",            // optional; segments events in the dashboard
    Release:          "v1.4.2",                // optional; ties events to a release
    SampleRate:       1.0,                     // optional; fraction of error events sent (1.0 = all)
    TracesSampleRate: 0.1,                     // optional; fraction of transactions traced
    Debug:            false,                   // optional; verbose Sentry SDK logging
})

For piko.yaml-driven setups, blank-import the package so the integration registers itself, then declare it under logger.integrations.

import _ "piko.sh/piko/wdk/logger/logger_integration_sentry"

logger:
  integrations:
    - type: sentry
      enabled: true
      sentry:
        dsn: ${SENTRY_DSN}
        environment: production
        release: v1.4.2
        eventLevel: error          # comma-separated level names that become Sentry events
        breadcrumbLevel: info      # comma-separated level names sent as Sentry log entries
        tracesSampleRate: 0.1
        sampleRate: 1.0
        ignoreErrors:
          - context canceled
        sendDefaultPII: false
        addSource: true

The entry must set enabled: true. The logger skips a type: sentry block without it and creates no handler. The package import must be present, or the logger treats the type as unavailable. The eventLevel, breadcrumbLevel, ignoreErrors, sendDefaultPII, and addSource settings reach the SDK only through this YAML path, not the public code Config.

Bootstrap

There is no piko.With* option for Sentry. The integration plugs into the logger through the registry that the package import populates. When wired in code, Enable is the bootstrap step and adds the slog handler. When wired through piko.yaml, the logger reads the integration entry during its own setup, so the blank import plus the config entry covers both the handler and the OTEL components.

For trace correlation, use the piko.yaml path. The logger collects the Sentry span processor and propagator only from config integrations marked enabled: true. The code-only Enable path adds the error handler and breadcrumbs but does not attach the OTEL components.

See also

Other logger integrations:

Framework docs:

External: