documentation/otel/otel-transformation-rules.md
This document describes the JSON schema for OpenTelemetry Transformation Rules, which define how transaction events, trace segments, and time slice metrics are synthesized from span data. The intention is the OpenTelemetry attributes are processed when a span ends to ensure all the attributes are available for the agent's telemetry processing. The segment naming occurs when a span starts for all segments except for the transaction segment which is processed when the span ends. The schema is designed to be strict, ensuring that all rules conform to a defined structure and that no unknown properties are allowed.
Note: This schema has only been tested with the Node.js agent, and while it is expected to work with other language agents, the implementation details may vary.
Each item in the array is a rule object with the following properties:
name (string):
The unique name of the transformation rule.
type (string):
The type of the rule. Must be one of: producer, consumer, external, server, db, internal.
matcher (object):
Defines the criteria for matching spans to this rule.
required_span_kinds (string[]):
List of span kinds required for this rule to match. Each must be one of: server, client, producer, consumer, internal.
required_attribute_keys (string[]):
List of attribute keys that must be present on the span.
attribute_conditions (object, optional):
An object where each key is an attribute name and the value is an array of allowed values for that attribute.
array, optional):key (string, optional):
The key of the span attribute to extract.
value (string|number|boolean, optional):
A literal value to use for the attribute.
template (string, optional):
A template string for constructing the attribute value.
regex (object, optional):
Describes how to extract values using regular expressions.
string, required): The regex pattern.string, optional): Regex flags.array, optional): Array of group extraction objects, each with:
integer|string): The group index or name.string, optional): The span attribute key(used to remove from trace segment)string, optional): The attribute name for the extracted value.object, optional): Nested regex extraction.
string, required): The regex pattern.string, optional): Regex flags.integer|string, optional): Value to extract.string, optional): Prefix to add to the extracted value.target (string, optional):
Where to assign the attribute (segment, transaction, or trace).
name (string, optional):
The name to use for the attribute in the target.
highSecurity (boolean, optional):
If true, the attribute is omitted in high-security mode.
mappings (array, optional):
Array of mapping objects for advanced transformations. Used to apply custom functions to the attribute value.(e.g. only include an attribute if it matches a certain condition)
string): Mapping key.string): Mapping function arguments(comma delimited).string): Mapping function body.object, optional):string, required): Transaction type. Must be one of: web, or messagestring, optional): messaging system span attribute.(consumer segments only)object, optional): Transaction naming details.
string, optional): span attribute to use as verb.(sever segments only)string, optional): span attribute to use as route(server segments only)string, optional): Prefix for the transaction name.(rpc server segments only)string, optional): template for the partial transaction name.string, optional): template for the transaction path.string, optional): Literal value for the transaction name.object, optional): URL construction details.(server segments only)
string, optional): template to construct the URL.string, optional): span attribute to use as URL.array, optional): Array of mapping for advanced URL transformations.
string): Mapping key.string): Mapping function arguments(comma delimited).string): Mapping function body.object, optional):object, optional): Segment naming details.
string, optional)string|object, optional): span attribute to use as host.(external segments only)
string, optional): template for the host.string, optional): span attribute to use as host.string, optional): span attribute to use as system.(producer and rpc external segments only)string, optional): span attribute to use as URL(external segments only)string, optional): span attribute to use as operation.(db segments only)string, optional): span attribute to use as type.(db segments only)string, optional): span attribute to use as sql query(db segments only)string, optional): span attribute to use as collection name(db segments only)Strictness:
The schema does not allow unknown properties at any level (additionalProperties: false).
Extensibility:
If you add new fields or structures, update the schema accordingly.
Validation:
Use this schema with a JSON Schema validator to ensure your transformation rules are well-formed and consistent.
Example Rule:
{
"name": "Producer_1_30",
"type": "producer",
"matcher": {
"required_span_kinds": ["producer"],
"required_attribute_keys": ["messaging.system", "messaging.destination.name"]
},
"attributes": [
{
"key": "server.address",
"target": "segment",
"name": "host"
}
],
"segment": {
"name": {
"template": "MessageBroker/${messaging.system}/${messaging.operation.name}/Produce/Named/${messaging.destination.name}"
}
}
}