Skip to content

docs: add throughput config options, NR auto-disable note, high-throughput example #48

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 3 commits into from
Apr 3, 2026
Merged

docs: add throughput config options, NR auto-disable note, high-throughput example #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7aa457f
docs: add throughput config options and high-throughput example
ankurs Apr 2, 2026
2ddae0b
fix: merge compression into HTTP Gateway section, clarify NR default,…
ankurs Apr 3, 2026
14d3349
fix: clarify LOG_LEVEL interaction, remove redundant example var
ankurs Apr 3, 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
2 changes: 1 addition & 1 deletion FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ ColdBrew generates a unique trace ID for every request automatically. It can als
1. **HTTP header** — `x-trace-id` (configurable via `TRACE_HEADER_NAME`) is forwarded from the HTTP gateway to gRPC
2. **Proto field** — if your request message has a `trace_id` string field, ColdBrew reads it via the generated `GetTraceId()` method

The trace ID is then propagated to structured logs (`"trace": "abc123"`) and Sentry/Rollbar error reports — so you can search for one ID and find the complete request flow across your logs and error tracking.
The trace ID is then propagated to structured logs (`"trace": "abc123"`), Sentry/Rollbar error reports, and OpenTelemetry spans (as the `coldbrew.trace_id` attribute) — so you can search for one ID and find the complete request flow across your logs, error tracking, and distributed traces.
Comment thread
ankurs marked this conversation as resolved.

See the [Tracing How-To](/howto/Tracing/#trace-id-propagation) for details.

Expand Down
26 changes: 25 additions & 1 deletion config-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,8 @@ cfg := config.GetColdBrewConfig()
| `JSON_BUILTIN_MARSHALLER_MIME` | string | `application/json` | Content-Type for the JSON builtin marshaller |
| `HTTP_HEADER_PREFIXES` | []string | `""` | HTTP header prefixes to forward as gRPC metadata (comma-separated) |
| `TRACE_HEADER_NAME` | string | `x-trace-id` | HTTP header name for trace ID propagation to log/trace contexts |
| `DISABLE_HTTP_COMPRESSION` | bool | `false` | Disable gzip/zstd compression for HTTP gateway responses |
| `HTTP_COMPRESSION_MIN_SIZE` | int | `256` | Minimum response body size (bytes) before compression is applied. Responses smaller than this are sent uncompressed |

## Prometheus Metrics

Expand All @@ -94,7 +96,7 @@ cfg := config.GetColdBrewConfig()
|----------|------|---------|-------------|
| `NEW_RELIC_LICENSE_KEY` | string | `""` | New Relic license key (required to enable New Relic) |
| `NEW_RELIC_APPNAME` | string | `""` | Application name in New Relic |
| `DISABLE_NEW_RELIC` | bool | `false` | Disable all New Relic reporting |
| `DISABLE_NEW_RELIC` | bool | `false` | Disable all New Relic reporting. **Note:** automatically set to `true` at startup when `NEW_RELIC_LICENSE_KEY` is empty, so the effective default for services without a license key is `true` |
| `NEW_RELIC_DISTRIBUTED_TRACING` | bool | `true` | Enable New Relic distributed tracing |
| `NEW_RELIC_OPENTELEMETRY` | bool | `true` | Enable New Relic via OpenTelemetry |
Comment thread
ankurs marked this conversation as resolved.
| `NEW_RELIC_OPENTELEMETRY_SAMPLE` | float64 | `0.2` | Trace sampling ratio for New Relic OpenTelemetry (0.0–1.0) |
Expand Down Expand Up @@ -127,6 +129,13 @@ When `OTLP_ENDPOINT` is set, it takes precedence over New Relic OpenTelemetry co
| `SHUTDOWN_DURATION_IN_SECONDS` | int | `15` | Time to wait for in-flight requests to complete before forced shutdown |
| `GRPC_GRACEFUL_DURATION_IN_SECONDS` | int | `7` | Time to wait for healthcheck failure to propagate before initiating shutdown. Should be less than `SHUTDOWN_DURATION_IN_SECONDS` |

## Response Time Logging

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `RESPONSE_TIME_LOG_LEVEL` | string | `info` | Log level for per-request response time logging. Valid: `debug`, `info`, `warn`, `error`. Invalid values fall back to `info`. Must be >= `LOG_LEVEL` to take effect |
| `RESPONSE_TIME_LOG_ERROR_ONLY` | bool | `false` | When `true`, only log response time for requests that return an error. Successful requests are not logged. Note: if `LOG_LEVEL` is set higher than `RESPONSE_TIME_LOG_LEVEL`, response time logs are already suppressed |

## Runtime

| Variable | Type | Default | Description |
Expand Down Expand Up @@ -164,6 +173,21 @@ export OTLP_SAMPLING_RATIO=1.0
export DISABLE_NEW_RELIC=true
```

## Example: High-Throughput Production

For services at 70k+ QPS where observability overhead matters:

```bash
export APP_NAME=myservice
export ENVIRONMENT=production
export LOG_LEVEL=warn # suppresses info-level response time logs
# export OTLP_ENDPOINT=your-collector:4317 # uncomment if using OTLP tracing
export OTLP_SAMPLING_RATIO=0.05 # only applies when OTLP_ENDPOINT is set
export ENABLE_PROMETHEUS_GRPC_HISTOGRAM=false
export DISABLE_NEW_RELIC=true
export HTTP_COMPRESSION_MIN_SIZE=512
```
Comment thread
ankurs marked this conversation as resolved.

---

Source: [`core/config/config.go`](https://github.com/go-coldbrew/core/blob/main/config/config.go)
Loading