Skip to content

api: support Formatter trace tag #7485

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

Open
zirain wants to merge 3 commits into
base: main
Choose a base branch
from
Open

api: support Formatter trace tag #7485

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
d5e5007
api: support Formatter trace tag
zirain Nov 11, 2025
ed0331a
update
zirain Nov 14, 2025
09213f2
fix
zirain Nov 14, 2025
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
23 changes: 22 additions & 1 deletion api/v1alpha1/envoyproxy_tracing_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,11 +94,19 @@ const (
CustomTagTypeEnvironment CustomTagType = "Environment"
// CustomTagTypeRequestHeader adds value from request header to each span.
CustomTagTypeRequestHeader CustomTagType = "RequestHeader"
// CustomTagTypeFormatter adds value using formatter to each span.
CustomTagTypeFormatter CustomTagType = "Formatter"
)

// CustomTag defines a custom tag to add to each span.
//
// +kubebuilder:validation:XValidation:message="formatter cannot be null when using Formatter type.",rule="self.type != 'Formatter' || has(self.formatter)"
// +kubebuilder:validation:XValidation:message="requestHeader cannot be null when using RequestHeader type.",rule="self.type != 'RequestHeader' || has(self.requestHeader)"
// +kubebuilder:validation:XValidation:message="environment cannot be null when using Environment type.",rule="self.type != 'Environment' || has(self.environment)"
// +kubebuilder:validation:XValidation:message="literal cannot be null when using Literal type.",rule="self.type != 'Literal' || has(self.literal)"
type CustomTag struct {
// Type defines the type of custom tag.
// +kubebuilder:validation:Enum=Literal;Environment;RequestHeader
// +kubebuilder:validation:Enum=Literal;Environment;RequestHeader;Formatter
// +unionDiscriminator
// +kubebuilder:default=Literal
Type CustomTagType `json:"type"`
Expand All @@ -111,6 +119,10 @@ type CustomTag struct {
// RequestHeader adds value from request header to each span.
// It's required when the type is "RequestHeader".
RequestHeader *RequestHeaderCustomTag `json:"requestHeader,omitempty"`
// Formatter adds value using formatter to each span.
// It's required when the type is "Formatter".
// +optional
Formatter *FormatterCustomTag `json:"formatter,omitempty"`
Copy link
Contributor

@arkodg arkodg Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

any reason we have 2 level here ?
does the similar field for access log use the same field name of formatter ?

Copy link
Member Author

@zirain zirain Nov 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there're two reasons why I used FormatterCustomTag here:

  1. keep same pattern with others type.
  2. in case there's more options in the future.

Copy link
Contributor

@jukie jukie Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Name does align with the changes from envoyproxy/envoy#41697


// TODO: add support for Metadata tags in the future.
// EG currently doesn't support metadata for route or cluster.
Expand Down Expand Up @@ -140,6 +152,15 @@ type RequestHeaderCustomTag struct {
DefaultValue *string `json:"defaultValue,omitempty"`
}

type FormatterCustomTag struct {
// Values defines the formatter value to use,
// same [formatter](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) as HTTP access logging
// (e.g. %REQUESTED_SERVER_NAME%).
// Unknown specifier values are replaced
// with the empty string.
Value string `json:"value"`
}

// ZipkinTracingProvider defines the Zipkin tracing provider configuration.
type ZipkinTracingProvider struct {
// Enable128BitTraceID determines whether a 128bit trace id will be used
Expand Down
20 changes: 20 additions & 0 deletions api/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

31 changes: 31 additions & 0 deletions ...s/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2309,6 +2309,8 @@ spec:
properties:
customTags:
additionalProperties:
description: CustomTag defines a custom tag to add to each
span.
properties:
environment:
description: |-
Expand All @@ -2326,6 +2328,22 @@ spec:
required:
- name
type: object
formatter:
description: |-
Formatter adds value using formatter to each span.
It's required when the type is "Formatter".
properties:
value:
description: |-
Values defines the formatter value to use,
same [formatter](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) as HTTP access logging
(e.g. %REQUESTED_SERVER_NAME%).
Unknown specifier values are replaced
with the empty string.
type: string
required:
- value
type: object
literal:
description: |-
Literal adds hard-coded value to each span.
Expand Down Expand Up @@ -2361,10 +2379,23 @@ spec:
- Literal
- Environment
- RequestHeader
- Formatter
type: string
required:
- type
type: object
x-kubernetes-validations:
- message: formatter cannot be null when using Formatter
type.
rule: self.type != 'Formatter' || has(self.formatter)
- message: requestHeader cannot be null when using RequestHeader
type.
rule: self.type != 'RequestHeader' || has(self.requestHeader)
- message: environment cannot be null when using Environment
type.
rule: self.type != 'Environment' || has(self.environment)
- message: literal cannot be null when using Literal type.
rule: self.type != 'Literal' || has(self.literal)
description: |-
CustomTags defines the custom tags to add to each span.
If provider is kubernetes, pod name and namespace are added by default.
Expand Down
31 changes: 31 additions & 0 deletions charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14817,6 +14817,8 @@ spec:
properties:
customTags:
additionalProperties:
description: CustomTag defines a custom tag to add to each
span.
properties:
environment:
description: |-
Expand All @@ -14834,6 +14836,22 @@ spec:
required:
- name
type: object
formatter:
description: |-
Formatter adds value using formatter to each span.
It's required when the type is "Formatter".
properties:
value:
description: |-
Values defines the formatter value to use,
same [formatter](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) as HTTP access logging
(e.g. %REQUESTED_SERVER_NAME%).
Unknown specifier values are replaced
with the empty string.
type: string
required:
- value
type: object
literal:
description: |-
Literal adds hard-coded value to each span.
Expand Down Expand Up @@ -14869,10 +14887,23 @@ spec:
- Literal
- Environment
- RequestHeader
- Formatter
type: string
required:
- type
type: object
x-kubernetes-validations:
- message: formatter cannot be null when using Formatter
type.
rule: self.type != 'Formatter' || has(self.formatter)
- message: requestHeader cannot be null when using RequestHeader
type.
rule: self.type != 'RequestHeader' || has(self.requestHeader)
- message: environment cannot be null when using Environment
type.
rule: self.type != 'Environment' || has(self.environment)
- message: literal cannot be null when using Literal type.
rule: self.type != 'Literal' || has(self.literal)
description: |-
CustomTags defines the custom tags to add to each span.
If provider is kubernetes, pod name and namespace are added by default.
Expand Down
31 changes: 31 additions & 0 deletions charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2308,6 +2308,8 @@ spec:
properties:
customTags:
additionalProperties:
description: CustomTag defines a custom tag to add to each
span.
properties:
environment:
description: |-
Expand All @@ -2325,6 +2327,22 @@ spec:
required:
- name
type: object
formatter:
description: |-
Formatter adds value using formatter to each span.
It's required when the type is "Formatter".
properties:
value:
description: |-
Values defines the formatter value to use,
same [formatter](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) as HTTP access logging
(e.g. %REQUESTED_SERVER_NAME%).
Unknown specifier values are replaced
with the empty string.
type: string
required:
- value
type: object
literal:
description: |-
Literal adds hard-coded value to each span.
Expand Down Expand Up @@ -2360,10 +2378,23 @@ spec:
- Literal
- Environment
- RequestHeader
- Formatter
type: string
required:
- type
type: object
x-kubernetes-validations:
- message: formatter cannot be null when using Formatter
type.
rule: self.type != 'Formatter' || has(self.formatter)
- message: requestHeader cannot be null when using RequestHeader
type.
rule: self.type != 'RequestHeader' || has(self.requestHeader)
- message: environment cannot be null when using Environment
type.
rule: self.type != 'Environment' || has(self.environment)
- message: literal cannot be null when using Literal type.
rule: self.type != 'Literal' || has(self.literal)
description: |-
CustomTags defines the custom tags to add to each span.
If provider is kubernetes, pod name and namespace are added by default.
Expand Down
31 changes: 31 additions & 0 deletions charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14816,6 +14816,8 @@ spec:
properties:
customTags:
additionalProperties:
description: CustomTag defines a custom tag to add to each
span.
properties:
environment:
description: |-
Expand All @@ -14833,6 +14835,22 @@ spec:
required:
- name
type: object
formatter:
description: |-
Formatter adds value using formatter to each span.
It's required when the type is "Formatter".
properties:
value:
description: |-
Values defines the formatter value to use,
same [formatter](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) as HTTP access logging
(e.g. %REQUESTED_SERVER_NAME%).
Unknown specifier values are replaced
with the empty string.
type: string
required:
- value
type: object
literal:
description: |-
Literal adds hard-coded value to each span.
Expand Down Expand Up @@ -14868,10 +14886,23 @@ spec:
- Literal
- Environment
- RequestHeader
- Formatter
type: string
required:
- type
type: object
x-kubernetes-validations:
- message: formatter cannot be null when using Formatter
type.
rule: self.type != 'Formatter' || has(self.formatter)
- message: requestHeader cannot be null when using RequestHeader
type.
rule: self.type != 'RequestHeader' || has(self.requestHeader)
- message: environment cannot be null when using Environment
type.
rule: self.type != 'Environment' || has(self.environment)
- message: literal cannot be null when using Literal type.
rule: self.type != 'Literal' || has(self.literal)
description: |-
CustomTags defines the custom tags to add to each span.
If provider is kubernetes, pod name and namespace are added by default.
Expand Down
18 changes: 17 additions & 1 deletion site/content/en/latest/api/extension_types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1098,7 +1098,7 @@ _Appears in:_




CustomTag defines a custom tag to add to each span.

_Appears in:_
- [ProxyTracing](#proxytracing)
Expand All @@ -1110,6 +1110,7 @@ _Appears in:_
| `literal` | _[LiteralCustomTag](#literalcustomtag)_ | true | | Literal adds hard-coded value to each span.<br />It's required when the type is "Literal". |
| `environment` | _[EnvironmentCustomTag](#environmentcustomtag)_ | true | | Environment adds value from environment variable to each span.<br />It's required when the type is "Environment". |
| `requestHeader` | _[RequestHeaderCustomTag](#requestheadercustomtag)_ | true | | RequestHeader adds value from request header to each span.<br />It's required when the type is "RequestHeader". |
| `formatter` | _[FormatterCustomTag](#formattercustomtag)_ | false | | Formatter adds value using formatter to each span.<br />It's required when the type is "Formatter". |


#### CustomTagType
Expand All @@ -1126,6 +1127,7 @@ _Appears in:_
| `Literal` | CustomTagTypeLiteral adds hard-coded value to each span.<br /> |
| `Environment` | CustomTagTypeEnvironment adds value from environment variable to each span.<br /> |
| `RequestHeader` | CustomTagTypeRequestHeader adds value from request header to each span.<br /> |
| `Formatter` | CustomTagTypeFormatter adds value using formatter to each span.<br /> |


#### DNS
Expand Down Expand Up @@ -2147,6 +2149,20 @@ _Appears in:_
| --- | --- | --- | --- | --- |


#### FormatterCustomTag





_Appears in:_
- [CustomTag](#customtag)

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | _string_ | true | | Values defines the formatter value to use,<br />same [formatter](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) as HTTP access logging<br />(e.g. %REQUESTED_SERVER_NAME%).<br />Unknown specifier values are replaced<br />with the empty string. |


#### GRPCActiveHealthChecker


Expand Down
Loading