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
- func BuildLogExporter(ctx context.Context, settings ExporterSettings) (sdklog.Exporter, error)
- func BuildMetricExporter(ctx context.Context, settings ExporterSettings) (sdkmetric.Exporter, error)
- func BuildResource(config cfg.Config, settings ResourceSettings) (*resource.Resource, error)
- func BuildTraceExporter(ctx context.Context, settings ExporterSettings) (sdktrace.SpanExporter, error)
- func ProvideResource(config cfg.Config) (*resource.Resource, error)
- type ExporterSettings
- type ResourceSettings
- type RetrySettings
- type Settings
- type TLSSettings
Constants ¶
const ( ProtocolGrpc = "grpc" ProtocolHttp = "http" )
ProtocolGrpc and ProtocolHttp are the supported OTLP transports.
const ConfigKey = "otel"
ConfigKey is the root config key for the shared OTEL settings.
Variables ¶
This section is empty.
Functions ¶
func BuildLogExporter ¶
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 ¶
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.
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.
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.