routingprocessor

package module
v0.132.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2025 License: Apache-2.0 Imports: 25 Imported by: 9

README

Routing processor

Status
Stability unmaintained: traces, metrics, logs
Deprecation of logs Date: 2024-12-05
Migration Note: Use routing connector (https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/36616)
Deprecation of metrics Date: 2024-12-05
Migration Note: Use routing connector (https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/36616)
Deprecation of traces Date: 2024-12-05
Migration Note: Use routing connector (https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/36616)
Distributions contrib
Issues Open issues Closed issues
Code coverage codecov
Code Owners
Emeritus @jpkrohling

Deprecation Notice

This processor has been deprecated in favor of the routing connector.

Migration

The routing connector supports all features of the routing processor and more. However, the configuration is different. The general idea is the same, but there are a few key differences:

  • Rather than routing directly to exporters, the routing connector routes to pipelines. This allow for processors to be included after routing decisions.
  • The connector is configured within the connectors section, rather than the processors section of the configuration.
  • Usage of the connector in pipelines is different. You must use it as an exporter AND as a receiver in each pipeline to which it can route.
  • Configuration is primarily based on OTTL.
  • Each route can be evaluated in a different OTTL Context.
Example

Starting from the example configuration below, we can achieve the same result with the routing connector:

processors:
  routing:
    from_attribute: X-Tenant
    default_exporters: [jaeger]
    table:
    - value: acme
      exporters: [jaeger/acme]
exporters:
  jaeger:
    endpoint: localhost:14250
  jaeger/acme:
    endpoint: localhost:24250
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [routing]
      exporters: [jaeger, jaeger/acme]

connectors:
  routing:
    match_once: true
    default_pipelines: [traces/jaeger]
    table:
    - context: request
      condition: request["X-Tenant"] == "acme"
      pipelines: [traces/jaeger/acme]
exporters:
  jaeger:
    endpoint: localhost:14250
  jaeger/acme:
    endpoint: localhost:24250
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [routing]
    traces/jaeger:
      receivers: [routing]
      exporters: [jaeger]
    traces/jaeger/acme:
      receivers: [routing]
      exporters: [jaeger/acme]

Overview

Routes logs, metrics or traces to specific exporters.

This processor will either read a header from the incoming HTTP request (gRPC or plain HTTP), or it will read a resource attribute, and direct the trace information to specific exporters based on the value read.

This processor does not let traces/metrics/logs to continue through the pipeline and will emit a warning in case other processor(s) are defined after this one. Similarly, exporters defined as part of the pipeline are not authoritative: if you add an exporter to the pipeline, make sure you add it to this processor as well, otherwise it won't be used at all. All exporters defined as part of this processor must also be defined as part of the pipeline's exporters.

Given that this processor depends on information provided by the client via HTTP headers or resource attributes, caution must be taken when processors that aggregate data like batch or groupbytrace are used as part of the pipeline.

Configuration

The following settings are required:

  • from_attribute: contains the HTTP header name or the resource attribute name to look up the route's value. Only the OTLP exporter has been tested in connection with the OTLP gRPC Receiver, but any other gRPC receiver should work fine, as long as the client sends the specified HTTP header.
  • table: the routing table for this processor.
  • table.value: a possible value for the attribute specified under FromAttribute.
  • table.exporters: the list of exporters to use when the value from the FromAttribute field matches this table item.

The following settings can be optionally configured:

  • attribute_source defines where to look for the attribute in from_attribute. The allowed values are:
    • context (the default) - to search the context, which includes HTTP headers
    • resource - to search the resource attributes.
  • drop_resource_routing_attribute - controls whether to remove the resource attribute used for routing. This is only relevant if AttributeSource is set to resource.
  • default_exporters contains the list of exporters to use when a more specific record can't be found in the routing table.

Example:

processors:
  routing:
    from_attribute: X-Tenant
    default_exporters:
    - jaeger
    table:
    - value: acme
      exporters: [jaeger/acme]
exporters:
  jaeger:
    endpoint: localhost:14250
  jaeger/acme:
    endpoint: localhost:24250
Tech Preview: OpenTelemetry Transformation Language statements as routing conditions

Alternatively, it is possible to use subset of the OpenTelemetry Transformation Language (OTTL) statements as routing conditions.

To configure the routing processor with OTTL routing conditions use the following options:

  • table (required): the routing table for this processor.
  • table.statement (required): the routing condition provided as the OTTL statement.
  • table.exporters (required): the list of exporters to use when the routing condition is met.
  • default_exporters (optional): contains the list of exporters to use when a record does not meet any of specified conditions.
  • error_mode (optional): determines how errors returned from OTTL statements are handled. Valid values are ignore and propagate. If ignored or silent is used and a statement's condition has an error then the payload will be routed to the default exporter. When silent is used the error is not logged. If not supplied, propagate is used.

processors:
  routing:
    default_exporters:
    - jaeger
    error_mode: ignore
    table:
      - statement: route() where resource.attributes["X-Tenant"] == "acme"
        exporters: [jaeger/acme]
      - statement: delete_key(resource.attributes, "X-Tenant") where IsMatch(resource.attributes["X-Tenant"], ".*corp")
        exporters: [jaeger/ecorp]

exporters:
  jaeger:
    endpoint: localhost:14250
  jaeger/acme:
    endpoint: localhost:24250
  jaeger/ecorp:
    endpoint: localhost:34250

A signal may get matched by routing conditions of more than one routing table entry. In this case, the signal will be routed to all exporters of matching routes. Respectively, if none of the routing conditions met, then a signal is routed to default exporters.

It is also possible to mix both the conventional routing configuration and the routing configuration with OTTL conditions.

Limitations:
  • OTTL statements can be applied only to resource attributes.
  • Currently, it is not possible to specify the boolean statements without function invocation as the routing condition. It is required to provide the NOOP route() or any other supported function as part of the routing statement, see #13545 for more information.
  • If data is received on OTLP http server, include_metadata must be set to true in order to use context based routing.
  • Supported OTTL functions:

The full list of settings exposed for this processor are documented in config.go with detailed sample configuration files:

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewFactory 

func NewFactory() processor.Factory

NewFactory creates a factory for the routing processor.

Types

type AttributeSource added in v0.38.0 

type AttributeSource string

type Config 

type Config struct {
	// DefaultExporters contains the list of exporters to use when a more specific record can't be found in the routing table.
	// Optional.
	DefaultExporters []string `mapstructure:"default_exporters"`

	// AttributeSource defines where the attribute defined in `from_attribute` is searched for.
	// The allowed values are:
	// - "context" - the attribute must exist in the incoming context
	// - "resource" - the attribute must exist in resource attributes
	// The default value is "context".
	// Optional.
	AttributeSource AttributeSource `mapstructure:"attribute_source"`

	// FromAttribute contains the attribute name to look up the route value. This attribute should be part of the context propagated
	// down from the previous receivers and/or processors. If all the receivers and processors are propagating the entire context correctly,
	// this could be the HTTP/gRPC header from the original request/RPC. Typically, aggregation processors (batch, groupbytrace)
	// will create a new context, so, those should be avoided when using this processor.Although the HTTP spec allows headers to be repeated,
	// this processor will only use the first value.
	// Required.
	FromAttribute string `mapstructure:"from_attribute"`

	// DropRoutingResourceAttribute controls whether to remove the resource attribute used for routing.
	// This is only relevant if AttributeSource is set to resource.
	// Optional.
	DropRoutingResourceAttribute bool `mapstructure:"drop_resource_routing_attribute"`

	// ErrorMode determines how the processor reacts to errors that occur while processing an OTTL condition.
	// Valid values are `ignore` and `propagate`.
	// `ignore` means the processor ignores errors returned by conditions and continues on to the next condition. This is the recommended mode.
	// If `ignored` is used and a statement's condition has an error then the payload will be routed to the default exporter.
	// `propagate` means the processor returns the error up the pipeline.  This will result in the payload being dropped from the collector.
	// The default value is `propagate`.
	ErrorMode ottl.ErrorMode `mapstructure:"error_mode"`

	// Table contains the routing table for this processor.
	// Required.
	Table []RoutingTableItem `mapstructure:"table"`
}

Config defines configuration for the Routing processor.

func (*Config) Validate added in v0.38.0 

func (c *Config) Validate() error

Validate checks if the processor configuration is valid.

type RoutingTableItem 

type RoutingTableItem struct {
	// Value represents a possible value for the field specified under FromAttribute.
	// Required when Statement isn't provided.
	Value string `mapstructure:"value"`

	// Statement is a OTTL statement used for making a routing decision.
	// Required when 'Value' isn't provided.
	Statement string `mapstructure:"statement"`

	// Exporters contains the list of exporters to use when the value from the FromAttribute field matches this table item.
	// When no exporters are specified, the ones specified under DefaultExporters are used, if any.
	// The routing processor will fail upon the first failure from these exporters.
	// Optional.
	Exporters []string `mapstructure:"exporters"`
}

RoutingTableItem specifies how data should be routed to the different exporters

Source Files

View all Source files

Directories

Path Synopsis
internal
common
metadata
metadatatest

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.