observability

type BatchConfig struct {
	// Timeout specifies how long to wait before sending a batch of spans.
	// Lower values reduce latency but increase network overhead.
	Timeout time.Duration `mapstructure:"timeout"`

	// Size limits the number of spans per export batch.
	// Smaller batches reduce latency, larger batches reduce overhead.
	Size int `mapstructure:"size"`
}

type Config struct {
	// Enabled controls whether observability is active.
	// When false, all observability operations become no-ops.
	Enabled bool `mapstructure:"enabled"`

	// Service contains service identification metadata.
	Service ServiceConfig `mapstructure:"service"`

	// Environment indicates the deployment environment (e.g., production, staging, development).
	Environment string `mapstructure:"environment"`

	// Trace contains tracing-specific configuration.
	Trace TraceConfig `mapstructure:"trace"`

	// Metrics contains metrics-specific configuration.
	Metrics MetricsConfig `mapstructure:"metrics"`

	// Logs contains logging-specific configuration.
	Logs LogsConfig `mapstructure:"logs"`
}

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

type ExportConfig struct {
	// Timeout specifies the maximum time to wait for span export.
	// Prevents slow backends from blocking the application.
	Timeout time.Duration `mapstructure:"timeout"`
}

type LogsConfig struct {
	// Enabled controls whether OTLP log export is active.
	// Can be used to disable log export while keeping traces/metrics enabled.
	// nil = apply default (true when observability is enabled), false = explicitly disabled.
	Enabled *bool `mapstructure:"enabled"`

	// Endpoint specifies where to send log data.
	// Special value "stdout" enables console logging for local development.
	// For production, use OTLP endpoint (e.g., "http://localhost:4318" for HTTP or "localhost:4317" for gRPC).
	Endpoint string `mapstructure:"endpoint"`

	// Protocol specifies the OTLP protocol to use: "http" or "grpc".
	// If empty, logs inherit the trace protocol.
	Protocol string `mapstructure:"protocol"`

	// Insecure controls whether to use insecure connections (no TLS).
	// Only applicable for OTLP endpoints (http/grpc). Falls back to trace setting when unset.
	Insecure *bool `mapstructure:"insecure"`

	// DisableStdout controls whether to disable stdout logging when OTLP is enabled.
	// When false (default), logs go to both stdout and OTLP (useful for development).
	// When true, logs only go to OTLP (production efficiency).
	DisableStdout bool `mapstructure:"disable_stdout"`

	// Headers allows custom HTTP headers for OTLP exporters.
	// Useful for authentication tokens or API keys.
	// If nil or empty, logs inherit trace headers.
	Headers map[string]string `mapstructure:"headers"`

	// Compression specifies the compression algorithm for OTLP export.
	// Supported values: "gzip", "none".
	// Default: "gzip" (recommended by New Relic for bandwidth reduction).
	Compression string `mapstructure:"compression"`

	// Batch contains batch processing configuration (reused from TraceConfig pattern).
	Batch BatchConfig `mapstructure:"batch"`

	// Export contains export timeout configuration (reused from TraceConfig pattern).
	Export ExportConfig `mapstructure:"export"`

	// Max contains maximum queue and batch size limits (reused from TraceConfig pattern).
	Max MaxConfig `mapstructure:"max"`

	// SlowRequestThreshold defines the latency threshold for marking HTTP requests as slow.
	// Requests exceeding this duration are logged with result_code="WARN" in action logs.
	// This is a system-wide threshold (no per-route overrides).
	// Default: 1 second.
	SlowRequestThreshold time.Duration `mapstructure:"slow_request_threshold"`

	// SamplingRate controls what fraction of INFO/DEBUG trace logs to export (0.0 to 1.0).
	// ERROR/WARN logs and action logs are always exported at 100%.
	// Sampling is deterministic per trace (all logs in a trace are sampled together).
	// 1.0 means export all INFO/DEBUG logs, 0.0 means export none (default).
	// nil = apply default (0.0 for backward compatibility).
	SamplingRate *float64 `mapstructure:"sampling_rate"`
}

type MaxBatchConfig struct {
	// Size limits the number of spans per export batch.
	// Smaller batches reduce latency, larger batches reduce overhead.
	Size int `mapstructure:"size"`
}

type MaxConfig struct {
	// Queue contains queue size configuration.
	Queue QueueConfig `mapstructure:"queue"`

	// Batch contains batch size configuration.
	Batch MaxBatchConfig `mapstructure:"batch"`
}

type MetricsConfig struct {
	// Enabled controls whether metrics collection is active.
	// Can be used to disable metrics while keeping tracing enabled.
	// nil = apply default (true when observability is enabled), false = explicitly disabled.
	Enabled *bool `mapstructure:"enabled"`

	// Endpoint specifies where to send metric data.
	// Special value "stdout" enables console logging for local development.
	// For production, use OTLP endpoint (e.g., "http://localhost:4318").
	Endpoint string `mapstructure:"endpoint"`

	// Protocol specifies the OTLP protocol to use: "http" or "grpc".
	// If empty, metrics inherit the trace protocol.
	Protocol string `mapstructure:"protocol"`

	// Insecure controls whether to use insecure connections (no TLS).
	// Only applicable for OTLP endpoints (http/grpc). Falls back to trace setting when unset.
	Insecure *bool `mapstructure:"insecure"`

	// Headers allows custom headers for OTLP exporters (e.g., DataDog API keys).
	// If nil or empty, metrics inherit trace headers.
	Headers map[string]string `mapstructure:"headers"`

	// Compression specifies the compression algorithm for OTLP export.
	// Supported values: "gzip", "none".
	// Default: "gzip" (recommended by New Relic for bandwidth reduction).
	Compression string `mapstructure:"compression"`

	// Temporality specifies the aggregation temporality for metrics.
	// Supported values: "delta", "cumulative".
	// Default: "cumulative" (OTEL SDK default).
	// New Relic recommends "delta" for better performance and lower memory usage.
	Temporality string `mapstructure:"temporality"`

	// HistogramAggregation specifies the histogram aggregation method.
	// Supported values: "exponential", "explicit".
	// Default: "explicit" (OTEL SDK default).
	// New Relic recommends "exponential" for better precision and lower memory overhead.
	HistogramAggregation string `mapstructure:"histogram_aggregation"`

	// Interval specifies how often to export metrics.
	// Shorter intervals provide more real-time data but increase overhead.
	Interval time.Duration `mapstructure:"interval"`

	// Export contains export timeout configuration.
	Export MetricsExportConfig `mapstructure:"export"`
}

type MetricsExportConfig struct {
	// Timeout specifies the maximum time to wait for metric export.
	// Prevents slow backends from blocking the application.
	Timeout time.Duration `mapstructure:"timeout"`
}

type Provider interface {
	// TracerProvider returns the configured trace provider.
	TracerProvider() trace.TracerProvider

	// MeterProvider returns the configured meter provider.
	MeterProvider() metric.MeterProvider

	// LoggerProvider returns the configured logger provider.
	// Returns nil if logging is disabled.
	LoggerProvider() *sdklog.LoggerProvider

	// ShouldDisableStdout returns true if stdout should be disabled when OTLP is enabled.
	// This method provides configuration access for logger integration.
	ShouldDisableStdout() bool

	// Shutdown gracefully shuts down the provider, flushing any pending data.
	// It should be called during application shutdown.
	Shutdown(ctx context.Context) error

	// ForceFlush immediately flushes any pending telemetry data.
	// Useful before critical operations or shutdown.
	ForceFlush(ctx context.Context) error
}

type QueueConfig struct {
	// Size limits the number of spans buffered for export.
	// Prevents memory exhaustion under high load.
	Size int `mapstructure:"size"`
}

type SampleConfig struct {
	// Rate controls what fraction of traces to collect (0.0 to 1.0).
	// 1.0 means collect all traces, 0.1 means collect 10% of traces, 0.0 means collect nothing.
	// Lower values reduce overhead and costs.
	// nil = apply default (1.0), explicit value = use that value (including 0.0).
	Rate *float64 `mapstructure:"rate"`
}

type ServiceConfig struct {
	// Name identifies the service in traces and metrics.
	// This is required when observability is enabled.
	Name string `mapstructure:"name"`

	// Version specifies the version of the service.
	// Used for filtering and grouping in observability backends.
	Version string `mapstructure:"version"`
}

type TraceConfig struct {
	// Enabled controls whether tracing is active.
	// Can be used to disable tracing while keeping metrics enabled.
	// nil = apply default (true when observability is enabled), false = explicitly disabled.
	Enabled *bool `mapstructure:"enabled"`

	// Endpoint specifies where to send trace data.
	// Special value "stdout" enables console logging for local development.
	// For production, use OTLP endpoint (e.g., "http://localhost:4318" for HTTP or "localhost:4317" for gRPC).
	Endpoint string `mapstructure:"endpoint"`

	// Protocol specifies the OTLP protocol to use: "http" or "grpc".
	// Only used when Endpoint is not "stdout".
	// HTTP uses OTLP/HTTP protocol (default port 4318).
	// gRPC uses OTLP/gRPC protocol (default port 4317).
	Protocol string `mapstructure:"protocol"`

	// Insecure controls whether to use insecure connections (no TLS).
	// Only applicable for OTLP endpoints (http/grpc).
	// Set to true for local development without TLS.
	Insecure bool `mapstructure:"insecure"`

	// Headers allows custom HTTP headers for OTLP exporters.
	// Useful for authentication tokens or API keys.
	// Format: map of header name to header value.
	Headers map[string]string `mapstructure:"headers"`

	// Compression specifies the compression algorithm for OTLP export.
	// Supported values: "gzip", "none".
	// Default: "gzip" (recommended by New Relic for bandwidth reduction).
	Compression string `mapstructure:"compression"`

	// Sample contains sampling configuration.
	Sample SampleConfig `mapstructure:"sample"`

	// Batch contains batch processing configuration.
	Batch BatchConfig `mapstructure:"batch"`

	// Export contains export timeout configuration.
	Export ExportConfig `mapstructure:"export"`

	// Max contains maximum queue and batch size limits.
	Max MaxConfig `mapstructure:"max"`
}