go-redis/redis · error

failed to create stream lag histogram: %w

Error message

failed to create stream lag histogram: %w

What it means

Returned by createRecorder (redisotel.go:336) when meter.Float64Histogram fails to create the 'redis.client.stream.lag' instrument. Only checked when MetricGroupStream is enabled.

Source

Thrown at extra/redisotel-native/redisotel.go:336

	var streamLag metric.Float64Histogram

	if cfg.isMetricGroupEnabled(MetricGroupStream) {
		var streamLagOpts []metric.Float64HistogramOption
		streamLagOpts = append(streamLagOpts,
			metric.WithDescription("The lag between message creation and consumption in a stream consumer group"),
			metric.WithUnit("s"),
		)
		if cfg.histAggregation == HistogramAggregationExplicitBucket {
			streamLagOpts = append(streamLagOpts,
				metric.WithExplicitBucketBoundaries(cfg.bucketsStreamProcessingDuration...),
			)
		}
		streamLag, err = meter.Float64Histogram(
			MetricStreamLag,
			streamLagOpts...,
		)
		if err != nil {
			return nil, fmt.Errorf("failed to create stream lag histogram: %w", err)
		}
	}

	// Create recorder
	recorder := &metricsRecorder{
		operationDuration:        operationDuration,
		connectionCount:          connectionCount,
		connectionCreateTime:     connectionCreateTime,
		connectionRelaxedTimeout: connectionRelaxedTimeout,
		connectionHandoff:        connectionHandoff,
		clientErrors:             clientErrors,
		maintenanceNotifications: maintenanceNotifications,
		connectionWaitTime:       connectionWaitTime,
		connectionClosed:         connectionClosed,
		connectionPendingReqs:    connectionPendingReqs,
		pubsubMessages:           pubsubMessages,
		streamLag:                streamLag,
		cfg:                      &cfg,

View on GitHub (pinned to 36d97525cd)

Solutions

1. Search for other registrations of 'redis.client.stream.lag' and reconcile unit ('s') and description metadata
2. Validate cfg.BucketsStreamLag contains monotonically increasing positive float64 values
3. Verify OTel SDK compatibility

Example fix

// before - bucket boundaries non-monotonic
cfg.BucketsStreamLag = []float64{10, 1, 100}

// after - monotonically increasing
cfg.BucketsStreamLag = []float64{1, 10, 100}

// Validate stream lag bucket boundaries
for i := 1; i < len(cfg.BucketsStreamLag); i++ {
    if cfg.BucketsStreamLag[i] <= cfg.BucketsStreamLag[i-1] {
        return fmt.Errorf("invalid bucket boundaries")
    }
}

if err := obs.Init(cfg); err != nil {
    if strings.Contains(err.Error(), "stream lag histogram") {
        log.Error("conflict on 'redis.client.stream.lag' or invalid bucket boundaries")
    }
}

When it happens

Trigger: Calling Init with MetricGroupFlagStream enabled, and the OTel SDK rejects the histogram creation.

Common situations: Another library registered 'redis.client.stream.lag' with conflicting unit or description; malformed cfg.BucketsStreamLag boundary values when using explicit bucket aggregation.

Related errors

• failed to create operation duration histogram: %w
• failed to create connection create time histogram: %w
• failed to create connection wait time histogram: %w
• failed to create metrics recorder: %w
• failed to create connection count metric: %w

AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06). Data as JSON: /data/errors/975da5fbc7d1415b.json. Report an issue: GitHub.