Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Logging

  • concept
Log format, log levels, and log management for Cloud Native Gateway.

Cloud Native Gateway uses structured JSON logging powered by the zap logging library. Cloud Native Gateway writes logs to stdout, making them compatible with standard container log collection in Kubernetes and OpenShift environments.

Log Format and Structure

Cloud Native Gateway emits all log entries as single-line JSON objects with the following fields:

Field Description

level

The log severity: debug, info, warn, or error.

ts

The timestamp in ISO 8601 format — for example, 2024-01-15T10:30:00.000Z.

caller

The source file and line number that produced the log entry.

msg

A human-readable description of the event.

stacktrace

Included automatically for error-level messages.

Cloud Native Gateway includes additional structured fields depending on the event. For example, connection events include connectionString and User fields, and error events include an error field with the error message.

Example Log Output

{"level":"info","ts":"2024-01-15T10:30:00.000Z","caller":"gateway/gateway.go:150","msg":"linking to couchbase cluster","connectionString":"localhost","User":"Administrator"}
{"level":"info","ts":"2024-01-15T10:30:01.000Z","caller":"gateway/gateway.go:180","msg":"connected to couchbase cluster"}
{"level":"info","ts":"2024-01-15T10:30:01.500Z","caller":"system/system.go:200","msg":"starting to run protostellar system","boundPsPort":18098,"boundDapiPort":18099}

Log Levels

Use the --log-level flag or the STG_LOG_LEVEL environment variable to set the log level. The default is info:

$ ./cloud-native-gateway --self-sign --log-level debug

Supported levels, from most to least verbose:

  • debug — Detailed diagnostic information, including request-level tracing and internal state changes.

  • info — Normal operational events such as startup, connection, and configuration changes.

  • warn — Unexpected but non-critical conditions, such as failed cluster pings during retry or configuration mismatches.

  • error — Failures that require attention, such as connection failures or TLS certificate errors.

You can change the log level at runtime without restarting Cloud Native Gateway:

  • SIGHUP — Send a SIGHUP signal to trigger a configuration reload. If the --log-level value has changed in the configuration file, the new level takes effect.

  • Config file watch — When started with --watch-config, Cloud Native Gateway automatically detects changes to the configuration file and applies the new log level.

Component-Level Logging

Cloud Native Gateway uses named loggers for its internal components. Each component’s log entries include the component name in the caller or logger name field, making it straightforward to filter logs:

  • gateway — Core gateway lifecycle and cluster connection.

  • gateway.data-impl — Protostellar gRPC data operations.

  • gateway.dapi-impl — Data API HTTP operations.

  • gateway.gateway-system — gRPC and HTTP server management.

  • gateway.cbauth — Authentication subsystem.

  • gateway.gocbcorex — Couchbase cluster client.

Log Redaction

Cloud Native Gateway does not emit user data — such as document keys or document content — in info, warn, or error level log messages. Sensitive credentials (such as the Couchbase Server password) are explicitly excluded from configuration logging.

When running with --log-level debug, Cloud Native Gateway logs additional request-level detail. In production environments, use info or warn log levels to minimize the risk of logging sensitive information.

Log redaction tags as used by Couchbase Server are not applied by Cloud Native Gateway. If you require tagged log redaction for compliance, filter or post-process Cloud Native Gateway logs before forwarding them to a shared log aggregator.

Prepare Logs for Support

Collect logs that cover the full issue window, including startup and shutdown events when possible.

Kubernetes Deployments

In Kubernetes deployments managed by the Couchbase Kubernetes Operator, Cloud Native Gateway runs as a sidecar container. To view Cloud Native Gateway logs for a specific pod:

$ kubectl logs pod/mycluster-0000 -c cloud-native-gateway

To capture logs from all Cloud Native Gateway sidecars in a namespace:

$ kubectl logs -l app=couchbase -c cloud-native-gateway -n my-namespace --prefix

Cloud Native Gateway logs are also collected automatically by the cbopinfo tool when generating a Couchbase Kubernetes Operator diagnostics archive.

Self-Managed Deployments

For self-managed deployments, redirect stdout to a file or log aggregator:

$ ./cloud-native-gateway --self-sign 2>&1 | tee /var/log/cng/gateway.log

Most log aggregation tools can load the structured JSON format directly without additional parsing.

Information to Include in Support Tickets

When filing a support ticket, include:

  • Cloud Native Gateway logs at the most granular level possible, ideally debug, covering the time window of the issue.

  • The Cloud Native Gateway version (shown in the startup log entry).

  • The Couchbase Server version and cluster topology.

  • The Cloud Native Gateway configuration flags or config file, with credentials redacted.

  • Client SDK version and connection string used.