hashicorp / hashicorp/consul

Runtime values are used as structured log event names or field keys

Open
#23,541 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
30.1k
Forks
4.6k
Avg merge
2d 6h
Merged PRs (30d)
43

Description

## Anti-pattern

there are two related but different logging patterns.

### 1. Dynamic structured field keys

The primary concern is logging calls where runtime data is passed in a structured field-key position. For key/value logging APIs, field keys define the log schema and should generally be stable, code-defined names.

These cases can create inconsistent log schemas, make queries and dashboards harder to write, and may increase field cardinality in downstream observability systems.

### 2. Dynamic `msg`

A minor concern is dynamically formatted log message text, especially when the `msg` field is used operationally for grouping, alerting, dashboards, or event-style aggregation.

Where stable grouping is desired, the preferred pattern is to keep `msg` reasonably stable and move runtime-specific details into structured fields.

## How to reproduce

Trigger any affected entrypoint listed below and inspect the emitted structured log record.

## Expected behavior

Log event names and structured field keys should remain stable across executions. Runtime-specific data should be emitted as structured field values under fixed, descriptive keys.

## Affected entrypoints

Commit: `12bf1754a577142428a2f0e6dc06b3c9b1ed6b03`

### Runtime warning or error text used as the event name

These entrypoints pass a runtime warning or error string directly as the log message. These sites should use a stable event name and move the runtime text into a structured field such as `warning` or `error`.

- `msg` `agent/auto-config/auto_config.go:119`
- `msg` `agent/consul/config_endpoint.go:73`
- `msg` `agent/consul/rpc.go:501`
- `msg` `agent/consul/rpc.go:515`
- `msg` `agent/consul/server_log_verification.go:82`

### Runtime values formatted into the event name

These entrypoints build the log message with `fmt.Sprintf` or pass dynamic text through a helper that eventually logs it as the event name. The stable part of the event should be the message, while the hostname, ARN, upstream ID, or peer identifier should be emitted as fields.

- `msg` `agent/connect/ca/provider_aws.go:490`
- `msg` `agent/xds/clusters.go:2092`
- `msg` `agent/xds/endpoints.go:118`
- `msg` `agent/xds/endpoints.go:774`

### gRPC logger adapter forwards arbitrary library text as event names

These entrypoints are adapter methods for `grpclog.LoggerV2`. They convert arbitrary gRPC log arguments into strings and pass those strings as log messages. Since the text is produced by an external library and may include runtime connection, transport, or request details, the wrapper should use a stable event name such as `grpc log emitted` and place the original text in a field like `grpc_message`.

- `msg` `logging/grpc.go:40`
- `msg` `logging/grpc.go:45`
- `msg` `logging/grpc.go:55`
- `msg` `logging/grpc.go:60`
- `msg` `logging/grpc.go:70`
- `msg` `logging/grpc.go:75`
- `msg` `logging/grpc.go:85`

### Runtime values used as structured field keys

These entrypoints corrupt the key/value layout of structured logging calls. Runtime objects or protocol values are interpreted as field keys, which expands the structured field schema and makes querying unreliable. They should use fixed field names and place runtime data only in values.

- `key` `agent/consul/rpc.go:354`
- `key` `connect/proxy/config.go:282`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.