otel

package
v0.65.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 27, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package otel provides the shared OpenTelemetry core used by gosoline's tracing, metric, and log integrations: a resource builder derived from the application identity and OTLP exporter builders (gRPC/HTTP, with TLS/mTLS) driven by the native gosoline config system.

Index

Constants

View Source
const (
	ProtocolGrpc = "grpc"
	ProtocolHttp = "http"
)

ProtocolGrpc and ProtocolHttp are the supported OTLP transports.

View Source
const ConfigKey = "otel"

ConfigKey is the root config key for the shared OTEL settings.

Variables

This section is empty.

Functions

func BuildLogExporter

func BuildLogExporter(ctx context.Context, settings ExporterSettings) (sdklog.Exporter, error)

BuildLogExporter creates an OTLP log exporter for the configured protocol.

func BuildMetricExporter

func BuildMetricExporter(ctx context.Context, settings ExporterSettings) (sdkmetric.Exporter, error)

BuildMetricExporter creates an OTLP metric exporter for the configured protocol.

func BuildResource

func BuildResource(config cfg.Config, settings ResourceSettings) (*resource.Resource, error)

BuildResource constructs an OTEL resource from the application identity and the configured resource settings. Identity (service name/namespace, environment, extra attributes) lives in resource attributes — never in metric names or span names. All three signals build the resource from the same settings so traces, metrics, and logs share identical resource attributes (required for correlation).

func BuildTraceExporter

func BuildTraceExporter(ctx context.Context, settings ExporterSettings) (sdktrace.SpanExporter, error)

BuildTraceExporter creates an OTLP span exporter for the configured protocol.

func ProvideResource

func ProvideResource(config cfg.Config) (*resource.Resource, error)

ProvideResource builds the OTEL resource for the given config. It is a thin wrapper over BuildResource that first reads the shared settings.

Types

type ExporterSettings

type ExporterSettings struct {
	// Protocol selects the OTLP transport: grpc (default) or http.
	Protocol string `cfg:"protocol" default:"grpc"`
	// Host is the collector host; override via env from pod metadata (status.hostIP).
	Host string `cfg:"host" default:"localhost"`
	// Port is the collector port (4317 for gRPC, 4318 for HTTP by convention).
	Port int `cfg:"port" default:"4317"`
	// Endpoint, when set, takes precedence over Host:Port.
	Endpoint string `cfg:"endpoint" default:""`
	// UrlPath overrides the HTTP signal path for all signals; empty uses the SDK defaults.
	// Per-signal paths (TracesUrlPath, MetricsUrlPath, LogsUrlPath) take precedence when set.
	UrlPath string `cfg:"url_path" default:""`
	// TracesUrlPath overrides the HTTP path for traces; falls back to UrlPath, then SDK default (/v1/traces).
	TracesUrlPath string `cfg:"traces_url_path" default:""`
	// MetricsUrlPath overrides the HTTP path for metrics; falls back to UrlPath, then SDK default (/v1/metrics).
	MetricsUrlPath string `cfg:"metrics_url_path" default:""`
	// LogsUrlPath overrides the HTTP path for logs; falls back to UrlPath, then SDK default (/v1/logs).
	LogsUrlPath string `cfg:"logs_url_path" default:""`
	// Insecure disables transport security; set false to enable TLS/mTLS.
	Insecure bool `cfg:"insecure" default:"true"`
	// Compression enables payload compression ("gzip" or "" / "none").
	Compression string `cfg:"compression" default:"gzip"`
	// Timeout bounds a single export attempt.
	Timeout time.Duration `cfg:"timeout" default:"10s"`
	// Headers are static headers attached to every export (auth, tenant, ...).
	Headers map[string]string `cfg:"headers"`
	// TLS configures transport security when Insecure is false.
	TLS TLSSettings `cfg:"tls"`
	// Retry configures the exporter's built-in retry behavior.
	Retry RetrySettings `cfg:"retry"`
}

ExporterSettings configures a single OTLP exporter shared by all signals (per-signal overrides possible).

func (ExporterSettings) Address

func (e ExporterSettings) Address() string

Address returns the exporter endpoint, preferring an explicit Endpoint over Host:Port.

func (ExporterSettings) LogsPath

func (e ExporterSettings) LogsPath() string

LogsPath returns the URL path for logs, preferring LogsUrlPath over UrlPath.

func (ExporterSettings) MetricsPath

func (e ExporterSettings) MetricsPath() string

MetricsPath returns the URL path for metrics, preferring MetricsUrlPath over UrlPath.

func (ExporterSettings) TracesPath

func (e ExporterSettings) TracesPath() string

TracesPath returns the URL path for traces, preferring TracesUrlPath over UrlPath.

type ResourceSettings

type ResourceSettings struct {
	// ServiceNamePattern is expanded via cfg.Identity.Format (placeholders: {app.name}, {app.env}, {app.namespace}, {app.tags.x}).
	ServiceNamePattern string `cfg:"service_name_pattern,nodecode" default:"{app.name}"`
	// ServiceNamespacePattern maps to the service.namespace resource attribute. An empty pattern disables the attribute.
	ServiceNamespacePattern string `cfg:"service_namespace_pattern,nodecode" default:"{app.namespace}"`
	// Delimiter is used when joining namespace parts during pattern expansion.
	Delimiter string `cfg:"delimiter" default:"-"`
	// Attributes are additional resource attributes; values may contain identity placeholders.
	Attributes map[string]string `cfg:"attributes"`
}

ResourceSettings configures the OTEL resource attributes derived from the app identity.

type RetrySettings

type RetrySettings struct {
	Enabled         bool          `cfg:"enabled" default:"true"`
	InitialInterval time.Duration `cfg:"initial_interval" default:"5s"`
	MaxInterval     time.Duration `cfg:"max_interval" default:"30s"`
	MaxElapsedTime  time.Duration `cfg:"max_elapsed_time" default:"300s"`
}

RetrySettings configures the OTLP exporter retry/backoff.

type Settings

type Settings struct {
	Resource ResourceSettings `cfg:"resource"`
	Exporter ExporterSettings `cfg:"exporter"`
}

Settings holds the shared OTEL configuration reused by all signals.

func ReadSettings

func ReadSettings(config cfg.Config) (*Settings, error)

ReadSettings unmarshals the shared OTEL settings from the config root.

type TLSSettings

type TLSSettings struct {
	CaFile             string `cfg:"ca_file" default:""`
	CertFile           string `cfg:"cert_file" default:""`
	KeyFile            string `cfg:"key_file" default:""`
	ServerName         string `cfg:"server_name" default:""`
	InsecureSkipVerify bool   `cfg:"insecure_skip_verify" default:"false"`
	// MinVersion is the minimum TLS version to accept (e.g. "1.2", "1.3"). Defaults to TLS 1.3.
	MinVersion string `cfg:"min_version" default:"1.3"`
}

TLSSettings configures TLS and, when client cert/key are set, mTLS.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL