diff --git a/FAQ.md b/FAQ.md index 8e1895d..3c762e7 100644 --- a/FAQ.md +++ b/FAQ.md @@ -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. See the [Tracing How-To](/howto/Tracing/#trace-id-propagation) for details. diff --git a/config-reference.md b/config-reference.md index fa21f30..ae63a6e 100644 --- a/config-reference.md +++ b/config-reference.md @@ -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 @@ -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 | | `NEW_RELIC_OPENTELEMETRY_SAMPLE` | float64 | `0.2` | Trace sampling ratio for New Relic OpenTelemetry (0.0–1.0) | @@ -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 | @@ -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 +``` + --- Source: [`core/config/config.go`](https://github.com/go-coldbrew/core/blob/main/config/config.go)