Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/temporal-sa/temporal-cloud-proxy/llms.txt

Use this file to discover all available pages before exploring further.

Temporal Cloud Proxy uses structured JSON logging via Uber Zap. Every log line is a self-contained JSON object, making it straightforward to ingest into log aggregators such as Grafana Loki, Datadog, or Amazon CloudWatch Logs. The log level is controlled at startup with the --level CLI flag and cannot be changed at runtime without restarting the proxy.

​
Log Levels

The proxy accepts four standard log levels. Specify any of these as the value of --level:

debug

Detailed per-request logs including the workload-id, the full gRPC method name, request arguments, and incoming gRPC metadata. Also logs namespace connection setup at startup. Use during development and active troubleshooting only — the volume is high in production.

info

Startup messages, server bind addresses, metrics endpoint address, and other significant lifecycle events. This is the default level and is appropriate for most production deployments.

warn

Configuration warnings that indicate a workload is running without a recommended security feature: missing worker authentication, missing payload encryption, or conflicting API key configuration. These are logged once at startup per affected workload.

error

Component initialisation failures (failed to create authenticator, failed to initialise logger, failed to initialise Prometheus), and gRPC server errors that prevent the proxy from operating. Minimal output — suitable for noisy production environments where you only want actionable alerts.

​
Usage

Pass --level as a CLI flag when starting the proxy binary tclp: 
# Default (info level) — suitable for most production deployments
./tclp --config config.yaml

# Debug level — verbose per-request logging for troubleshooting
./tclp --config config.yaml --level debug

# Warn level — startup warnings only, no per-request noise
./tclp --config config.yaml --level warn

# Error level — minimal output, actionable failures only
./tclp --config config.yaml --level error
If an invalid log level string is supplied, the proxy exits immediately with an error before starting. Valid values are debug, info, warn, and error (case-sensitive, lowercase).

​
Log Output Format

The logger is initialised with zap.NewProductionConfig(), which produces newline-delimited JSON. Each log entry contains at minimum the fields level, ts (Unix timestamp in seconds with millisecond precision), and msg. Additional context fields are appended as key-value pairs within the same JSON object. Example startup output at info level: 
{"level":"info","ts":1234567890.123,"msg":"proxy started","host":"0.0.0.0","port":7233}
{"level":"info","ts":1234567890.456,"msg":"metrics server started","endpoint":"0.0.0.0:9090/metrics"}
Example output at debug level for an inbound gRPC call: 
{"level":"debug","ts":1234567890.789,"msg":"invoking method","workload-id":"production","method":"/temporal.api.workflowservice.v1.WorkflowService/StartWorkflowExecution"}
At debug level the proxy also logs namespace connection setup during initialisation: 
{"level":"debug","ts":1234567890.001,"msg":"adding namespace connection","workload-id":"production","namespace":"prod.mycompany"}

​
Warning Messages

The following warning messages are emitted once per workload during proxy startup. They do not prevent the proxy from starting, but indicate a workload is running in a reduced-security configuration:
Warning messageCauseRecommended action
workload configured without worker authenticationThe workload’s configuration has no authentication block, so any caller can route requests through this workload without presenting a token.Add a jwt or spiffe authentication block to the workload config.
workload configured without payload encryptionThe workload’s configuration has no encryption block, so Temporal payloads are forwarded to Temporal Cloud in plaintext.Add an aws-kms or gcp-kms encryption block to the workload config.
both value and envvar provider for api key; using valueBoth value and env are set on a workload’s temporal_cloud.authentication.api_key block. The proxy uses the literal value and ignores env.Remove the redundant field to avoid confusion about which key is in use.
In production, pipe JSON logs to a log aggregator (Loki, Datadog, CloudWatch) and filter on the workload-id field to isolate per-workload issues. For example, in Loki:
{job="temporal-cloud-proxy"} | json | workload_id="production"
At debug level, the full gRPC method name in the method field lets you identify which Temporal API operations are being called by each workload.

Build docs developers (and LLMs) love

Get started for freeTalk to us