Skip to content

feat: native stats/opentelemetry + OTEL metrics + OpenTracing removal #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ankurs merged 10 commits into from
Apr 8, 2026
Merged

feat: native stats/opentelemetry + OTEL metrics + OpenTracing removal #71

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
c6f4f88
feat: migrate gRPC OTel to native stats/opentelemetry, add OTEL metri…
ankurs Apr 7, 2026
6e8c963
fix: address PR review comments
ankurs Apr 7, 2026
77cb9eb
fix: capture providers in closures, clean up comments and unused code
ankurs Apr 7, 2026
c75e65b
fix: support ENABLE_OTEL_METRICS on New Relic OTLP path
ankurs Apr 7, 2026
d3c7cfc
fix: validate ServiceName only in fallback resource path
ankurs Apr 7, 2026
eb88fa2
fix: validate metrics interval, restore all globals in tests
ankurs Apr 7, 2026
c448797
fix: warn on metrics without endpoint, harden test isolation
ankurs Apr 7, 2026
a4481c5
fix: only populate NR otlpConfig when license key is non-empty
ankurs Apr 7, 2026
e934b32
refactor: extract NR endpoint const, inline trace opts helper, merge …
ankurs Apr 7, 2026
94e534f
fix: save/restore otelResource in TestBuildOTELResource to prevent or…
ankurs Apr 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 56 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,14 +87,17 @@ For full documentation, visit https://docs.coldbrew.cloud
- [Constants](<#constants>)
- [func ConfigureInterceptors\(DoNotLogGRPCReflection bool, traceHeaderName string, responseTimeLogLevel string, responseTimeLogErrorOnly bool\)](<#ConfigureInterceptors>)
- [func InitializeVTProto\(\)](<#InitializeVTProto>)
- [func OTELMeterProvider\(\) otelmetric.MeterProvider](<#OTELMeterProvider>)
- [func SetOTELGRPCClientOptions\(opts ...otelgrpc.Option\)](<#SetOTELGRPCClientOptions>)
- [func SetOTELGRPCServerOptions\(opts ...otelgrpc.Option\)](<#SetOTELGRPCServerOptions>)
- [func SetOTELOptions\(opts grpcotel.Options\)](<#SetOTELOptions>)
- [func SetupAutoMaxProcs\(\)](<#SetupAutoMaxProcs>)
- [func SetupEnvironment\(env string\)](<#SetupEnvironment>)
- [func SetupHystrixPrometheus\(\)](<#SetupHystrixPrometheus>)
- [func SetupLogger\(logLevel string, jsonlogs bool\) error](<#SetupLogger>)
- [func SetupNROpenTelemetry\(serviceName, license, version string, ratio float64\) error](<#SetupNROpenTelemetry>)
- [func SetupNewRelic\(serviceName, apiKey string, tracing bool\) error](<#SetupNewRelic>)
- [func SetupOTELMetrics\(config OTLPConfig, interval time.Duration\) \(\*sdkmetric.MeterProvider, error\)](<#SetupOTELMetrics>)
- [func SetupOpenTelemetry\(config OTLPConfig\) error](<#SetupOpenTelemetry>)
- [func SetupReleaseName\(rel string\)](<#SetupReleaseName>)
- [func SetupSentry\(dsn string\)](<#SetupSentry>)
Expand All @@ -115,7 +118,7 @@ const SupportPackageIsVersion1 = true
```

<a name="ConfigureInterceptors"></a>
## func [ConfigureInterceptors](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L325>)
## func [ConfigureInterceptors](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L388>)

```go
func ConfigureInterceptors(DoNotLogGRPCReflection bool, traceHeaderName string, responseTimeLogLevel string, responseTimeLogErrorOnly bool)
Expand All @@ -124,7 +127,7 @@ func ConfigureInterceptors(DoNotLogGRPCReflection bool, traceHeaderName string,
ConfigureInterceptors configures the interceptors package with the provided settings.

<a name="InitializeVTProto"></a>
## func [InitializeVTProto](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L380>)
## func [InitializeVTProto](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L443>)

```go
func InitializeVTProto()
Expand All @@ -134,26 +137,44 @@ InitializeVTProto initializes the vtproto package for use with the service

https://github.com/planetscale/vtprotobuf?tab=readme-ov-file#mixing-protobuf-implementations-with-grpc

<a name="OTELMeterProvider"></a>
## func [OTELMeterProvider](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L343>)

```go
func OTELMeterProvider() otelmetric.MeterProvider
```

OTELMeterProvider returns the global OTel MeterProvider. This is a convenience accessor for code that needs the interface type.

<a name="SetOTELGRPCClientOptions"></a>
## func [SetOTELGRPCClientOptions](<https://github.com/go-coldbrew/core/blob/main/core.go#L508>)
## func [SetOTELGRPCClientOptions](<https://github.com/go-coldbrew/core/blob/main/core.go#L558>)

```go
func SetOTELGRPCClientOptions(opts ...otelgrpc.Option)
```

SetOTELGRPCClientOptions sets options for the OTEL gRPC client stats handler. Must be called during init, before the gRPC client is created.
Deprecated: Use SetOTELOptions instead. Only applies when OTEL\_USE\_LEGACY\_INSTRUMENTATION=true.

<a name="SetOTELGRPCServerOptions"></a>
## func [SetOTELGRPCServerOptions](<https://github.com/go-coldbrew/core/blob/main/core.go#L502>)
## func [SetOTELGRPCServerOptions](<https://github.com/go-coldbrew/core/blob/main/core.go#L552>)

```go
func SetOTELGRPCServerOptions(opts ...otelgrpc.Option)
```

SetOTELGRPCServerOptions sets options for the OTEL gRPC server stats handler. Must be called during init, before the gRPC server starts. Example: core.SetOTELGRPCServerOptions\(otelgrpc.WithFilter\(...\)\)
Deprecated: Use SetOTELOptions instead. Only applies when OTEL\_USE\_LEGACY\_INSTRUMENTATION=true.

<a name="SetOTELOptions"></a>
## func [SetOTELOptions](<https://github.com/go-coldbrew/core/blob/main/core.go#L565>)

```go
func SetOTELOptions(opts grpcotel.Options)
```

SetOTELOptions configures the native gRPC stats/opentelemetry integration. Must be called during init, before the gRPC server starts. When set, processConfig\(\) will NOT overwrite these with auto\-built options.

<a name="SetupAutoMaxProcs"></a>
## func [SetupAutoMaxProcs](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L346>)
## func [SetupAutoMaxProcs](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L409>)

```go
func SetupAutoMaxProcs()
Expand All @@ -162,7 +183,7 @@ func SetupAutoMaxProcs()
SetupAutoMaxProcs sets up the GOMAXPROCS to match Linux container CPU quota This is used to set the GOMAXPROCS to the number of CPUs allocated to the container

<a name="SetupEnvironment"></a>
## func [SetupEnvironment](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L97>)
## func [SetupEnvironment](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L98>)

```go
func SetupEnvironment(env string)
Expand All @@ -171,7 +192,7 @@ func SetupEnvironment(env string)
SetupEnvironment sets the environment This is used to identify the environment in Sentry and New Relic env is the environment to set for the service \(e.g. prod, staging, dev\)

<a name="SetupHystrixPrometheus"></a>
## func [SetupHystrixPrometheus](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L317>)
## func [SetupHystrixPrometheus](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L380>)

```go
func SetupHystrixPrometheus()
Expand All @@ -180,7 +201,7 @@ func SetupHystrixPrometheus()
SetupHystrixPrometheus sets up the hystrix metrics This is a workaround for hystrix\-go not supporting the prometheus registry It uses sync.Once to ensure the Prometheus collectors are only registered once, since duplicate registration panics.

<a name="SetupLogger"></a>
## func [SetupLogger](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L73>)
## func [SetupLogger](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L74>)

```go
func SetupLogger(logLevel string, jsonlogs bool) error
Expand All @@ -189,7 +210,7 @@ func SetupLogger(logLevel string, jsonlogs bool) error
SetupLogger sets up the logger It uses the coldbrew logger to log messages to stdout logLevel is the log level to set for the logger jsonlogs is a boolean to enable or disable json logs

<a name="SetupNROpenTelemetry"></a>
## func [SetupNROpenTelemetry](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L293>)
## func [SetupNROpenTelemetry](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L357>)

```go
func SetupNROpenTelemetry(serviceName, license, version string, ratio float64) error
Expand All @@ -207,35 +228,45 @@ Parameters:
- ratio: the sampling ratio to use for traces \(0.0 to 1.0\)

<a name="SetupNewRelic"></a>
## func [SetupNewRelic](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L47>)
## func [SetupNewRelic](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L48>)

```go
func SetupNewRelic(serviceName, apiKey string, tracing bool) error
```

SetupNewRelic sets up the New Relic tracing and monitoring agent for the service It uses the New Relic Go Agent to send traces to New Relic One APM and Insights serviceName is the name of the service apiKey is the New Relic license key tracing is a boolean to enable or disable tracing

<a name="SetupOTELMetrics"></a>
## func [SetupOTELMetrics](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L294>)

```go
func SetupOTELMetrics(config OTLPConfig, interval time.Duration) (*sdkmetric.MeterProvider, error)
```

SetupOTELMetrics creates a MeterProvider with an OTLP gRPC exporter that reuses the same resource as the TracerProvider \(set by SetupOpenTelemetry\). The MeterProvider is set as the global OTel MeterProvider.

Call this after SetupOpenTelemetry so the shared resource is available.

<a name="SetupOpenTelemetry"></a>
## func [SetupOpenTelemetry](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L178>)
## func [SetupOpenTelemetry](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L234>)

```go
func SetupOpenTelemetry(config OTLPConfig) error
```

SetupOpenTelemetry sets up OpenTelemetry tracing with a generic OTLP exporter
SetupOpenTelemetry sets up OpenTelemetry tracing with a generic OTLP exporter.

This function provides a flexible way to configure OpenTelemetry tracing with any OTLP\-compatible backend. It sets up the trace provider, configures sampling, and optionally sets up an OpenTracing bridge for compatibility.
It configures a TracerProvider with the given sampling ratio and OTLP backend, sets it as the global provider, and stores it for graceful shutdown.

Example usage with Jaeger:

```
config := OTLPConfig{
Endpoint: "localhost:4317",
ServiceName: "my-service",
ServiceVersion: "v1.0.0",
SamplingRatio: 0.1,
UseOpenTracingBridge: true,
Insecure: true, // for local development
Endpoint: "localhost:4317",
ServiceName: "my-service",
ServiceVersion: "v1.0.0",
SamplingRatio: 0.1,
Insecure: true, // for local development
}
err := SetupOpenTelemetry(config)
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Expand All @@ -254,7 +285,7 @@ err := SetupOpenTelemetry(config)
```

<a name="SetupReleaseName"></a>
## func [SetupReleaseName](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L106>)
## func [SetupReleaseName](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L107>)

```go
func SetupReleaseName(rel string)
Expand All @@ -263,7 +294,7 @@ func SetupReleaseName(rel string)
SetupReleaseName sets the release name This is used to identify the release in Sentry rel is the release name to set for the service \(e.g. v1.0.0\)

<a name="SetupSentry"></a>
## func [SetupSentry](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L88>)
## func [SetupSentry](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L89>)

```go
func SetupSentry(dsn string)
Expand Down Expand Up @@ -293,7 +324,7 @@ type CB interface {
```

<a name="New"></a>
### func [New](<https://github.com/go-coldbrew/core/blob/main/core.go#L793>)
### func [New](<https://github.com/go-coldbrew/core/blob/main/core.go#L878>)

```go
func New(c config.Config) CB
Expand Down Expand Up @@ -346,7 +377,7 @@ type CBStopper interface {
```

<a name="OTLPConfig"></a>
## type [OTLPConfig](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L116-L148>)
## type [OTLPConfig](<https://github.com/go-coldbrew/core/blob/main/initializers.go#L117-L145>)

OTLPConfig holds configuration for OpenTelemetry OTLP exporter

Expand Down Expand Up @@ -378,10 +409,6 @@ type OTLPConfig struct {
// If empty, defaults to "gzip"
Compression string

// UseOpenTracingBridge determines whether to set up OpenTracing compatibility bridge
// This allows using OpenTracing instrumentation with OpenTelemetry
UseOpenTracingBridge bool

// Insecure disables TLS verification for the connection
// Only use this for local development or testing
Insecure bool
Expand Down
21 changes: 16 additions & 5 deletions config/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ import "github.com/go-coldbrew/core/config"


<a name="Config"></a>
## type [Config](<https://github.com/go-coldbrew/core/blob/main/config/config.go#L6-L159>)
## type [Config](<https://github.com/go-coldbrew/core/blob/main/config/config.go#L6-L170>)

Config is the configuration for the Coldbrew server It is populated from environment variables and has sensible defaults for all fields so that you can just use it as is without any configuration The following environment variables are supported and can be used to override the defaults for the fields

Expand Down Expand Up @@ -199,11 +199,22 @@ type Config struct {
// OTLPSamplingRatio is the ratio of traces to sample (0.0 to 1.0)
// 1.0 means sample all traces, 0.1 means sample 10% of traces
OTLPSamplingRatio float64 `envconfig:"OTLP_SAMPLING_RATIO" default:"0.1"`
// Deprecated: OpenTracing bridge is provided for backwards compatibility only.
// New services should leave this false (the default). Set to true only if you
// have existing OpenTracing instrumentation that hasn't been migrated to OTEL.
// Deprecated: OpenTracing bridge has been removed. This field is ignored.
// If set to true, a warning is logged at startup.
OTLPUseOpenTracingBridge bool `envconfig:"OTLP_USE_OPENTRACING_BRIDGE" default:"false"`

// OTELUseLegacyInstrumentation reverts to the deprecated otelgrpc contrib
// package for gRPC OpenTelemetry instrumentation. Default false (uses native
// grpc stats/opentelemetry). Set to true only for rollback.
OTELUseLegacyInstrumentation bool `envconfig:"OTEL_USE_LEGACY_INSTRUMENTATION" default:"false"`

// EnableOTELMetrics enables OpenTelemetry metrics export via OTLP alongside
// Prometheus. Does not replace Prometheus. Default false.
EnableOTELMetrics bool `envconfig:"ENABLE_OTEL_METRICS" default:"false"`
// OTELMetricsInterval controls the export interval in seconds for OTEL
// metrics. Default 60.
OTELMetricsInterval int `envconfig:"OTEL_METRICS_INTERVAL" default:"60"`

// DisableHTTPCompression disables gzip/zstd compression for HTTP gateway responses
DisableHTTPCompression bool `envconfig:"DISABLE_HTTP_COMPRESSION" default:"false"`
// HTTPCompressionMinSize is the minimum response body size (bytes) before compression is applied.
Expand All @@ -223,7 +234,7 @@ type Config struct {
```

<a name="Config.Validate"></a>
### func \(Config\) [Validate](<https://github.com/go-coldbrew/core/blob/main/config/config.go#L164>)
### func \(Config\) [Validate](<https://github.com/go-coldbrew/core/blob/main/config/config.go#L175>)

```go
func (c Config) Validate() []string
Expand Down
20 changes: 17 additions & 3 deletions config/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,11 +134,22 @@ type Config struct {
// OTLPSamplingRatio is the ratio of traces to sample (0.0 to 1.0)
// 1.0 means sample all traces, 0.1 means sample 10% of traces
OTLPSamplingRatio float64 `envconfig:"OTLP_SAMPLING_RATIO" default:"0.1"`
// Deprecated: OpenTracing bridge is provided for backwards compatibility only.
// New services should leave this false (the default). Set to true only if you
// have existing OpenTracing instrumentation that hasn't been migrated to OTEL.
// Deprecated: OpenTracing bridge has been removed. This field is ignored.
// If set to true, a warning is logged at startup.
OTLPUseOpenTracingBridge bool `envconfig:"OTLP_USE_OPENTRACING_BRIDGE" default:"false"`

// OTELUseLegacyInstrumentation reverts to the deprecated otelgrpc contrib
// package for gRPC OpenTelemetry instrumentation. Default false (uses native
// grpc stats/opentelemetry). Set to true only for rollback.
OTELUseLegacyInstrumentation bool `envconfig:"OTEL_USE_LEGACY_INSTRUMENTATION" default:"false"`

// EnableOTELMetrics enables OpenTelemetry metrics export via OTLP alongside
// Prometheus. Does not replace Prometheus. Default false.
EnableOTELMetrics bool `envconfig:"ENABLE_OTEL_METRICS" default:"false"`
// OTELMetricsInterval controls the export interval in seconds for OTEL
// metrics. Default 60.
OTELMetricsInterval int `envconfig:"OTEL_METRICS_INTERVAL" default:"60"`
Comment thread
ankurs marked this conversation as resolved.

// Throughput tuning

// DisableHTTPCompression disables gzip/zstd compression for HTTP gateway responses
Expand Down Expand Up @@ -189,6 +200,9 @@ func (c Config) Validate() []string {
if c.HTTPCompressionMinSize < 0 {
warnings = append(warnings, "HTTPCompressionMinSize is negative; this may cause unexpected behavior")
}
if c.EnableOTELMetrics && c.OTELMetricsInterval <= 0 {
warnings = append(warnings, "OTELMetricsInterval should be positive when ENABLE_OTEL_METRICS is true")
}

return warnings
}
Loading
Loading