odigos.io/v1alpha1

Allows you to attach a meaningful name to the action for convenience. Odigos does not use or assume any meaning from this field.

A free-form text field that allows you to attach notes regarding the action for convenience. For example: why it was added. Odigos does not use or assume any meaning from this field.

A boolean field allowing to temporarily disable the action, but keep it around for future use

Which signals should this action operate on.

AddClusterInfo is the config for the AddClusterInfo Action.

DeleteAttribute is the config for the DeleteAttribute Action.

RenameAttribute is the config for the RenameAttribute Action.

PiiMasking is the config for the PiiMasking Action.

K8sAttributes is the config for the K8sAttributes Action.

Samplers is the config for the Samplers Action.

URLTemplatization is the config for the URLTemplatization Action.

SpanRenamer is the config for the SpanRenamer Action.

Represents the observations of a action’s current state. Known .status.conditions.type are: “Available”, “Progressing”

if not nil, it means agent should report span metrics, calculated directly in the agent. this is most accurate as it includes any sampled spans, and is not affected if spans are dropped anywhere in the pipeline.

if not nil, it means agent should report runtime metrics, such as JVM metrics for Java applications. these metrics provide insights into the runtime environment performance.

additional dimensions to add for the span metrics. for example, if you add http.method to the dimensions, then the span metrics data points will include the http.method in the attributes, and different values of http.method will be aggregated into different time series.

time interval in miliseconds for flushing the span metrics. defaults: 60000 (60 seconds, 1 minute)

explicit buckets list for the histogram metrics in ms

id generator configuration for the traces. if not specified, the default random id generator will be used.

A list of URL templatization configurations to be applied to the traces.

Configuration for headers collection. If not specified, no headers will be collected.

HeadSamplingConfig is a set sampling rules. This config currently only applies to root spans. In the Future we might add another level of configuration base on the parent span (ParentBased Sampling)

Configuration for span renamer.

attribute key (e.g. “url.path”)

currently only string values are supported.

The operator to use to compare the attribute value.

The fraction of spans to sample, in the range [0, 1]. If the fraction is 0, no spans are sampled. If the fraction is 1, all spans are sampled.

if not nil for node collector, it means span to metrics is enabled, and the node collector should set it up in the pipeline. span to metrics is the ability to calculate metrics like http requests/errors/duration etc from the individual spans recorded for relevant operation.

if not nil for node collector, it means host metrics is enabled, and the opentelemetry collector “hostmetrics” receiver should be included in the pipeline. host metrics are metrics that are collected from the host node, such as cpu, memory, disk, network, etc.

if not nil for node collector, it means kubelet stats is enabled, and the opentelemetry collector “kubeletstats” receiver should be included in the pipeline. kubelet stats are metrics that are collected from the kubelet point of view, such as cpu, memory, disk, network, per pod, node and more.

if not nil for cluster collector, it means service graph is enabled, and metrics for the “connectivity” between services should be calculated to be exported to metrics destinations.

if not nil for node collector, it means that some metric destinations are intresseted in collecting metrics about: odigos, the collected data, and the pipeline itself. this allows for users to monitor and operate odigos within their existing system, create dashboards, alerting, and more.

this part controls the metrics which are received from agents in the otlp receiver. it is generally enabled when we want to record metrics, and listed here for completeness. any “otlp receiver” specific settings can go here

Minumum + Maximum number of replicas for the collector - these relevant only for gateway.

MemoryRequestMiB is the memory resource request to be used on the pod template. it will be embedded in the as a resource request of the form memory: <value>Mi

This option sets the limit on the memory usage of the collector. since the memory limiter mechanism is heuristic, and operates on fixed intervals, while it cannot fully prevent OOMs, it can help in reducing the chances of OOMs in edge cases. the settings should prevent the collector from exceeding the memory request, so one can set this to the same value as the memory request or higher to allow for some buffer for bursts.

CPU resource request to be used on the pod template. it will be embedded in the as a resource request of the form cpu: <value>m

CPU resource limit to be used on the pod template. it will be embedded in the as a resource limit of the form cpu: <value>m

this parameter sets the “limit_mib” parameter in the memory limiter configuration for the collector. it is the hard limit after which a force garbage collection will be performed. this value will end up comparing against the go runtime reported heap Alloc value. According to the memory limiter docs:

this parameter sets the “spike_limit_mib” parameter in the memory limiter configuration for the collector memory limiter. note that this is not the processor soft limit itself, but the diff in Mib between the hard limit and the soft limit. according to the memory limiter docs, it is recommended to set this to 20% of the hard limit. changing this value allows trade-offs between memory usage and resiliency to bursts.

the GOMEMLIMIT environment variable value for the collector pod. this is when go runtime will start garbage collection. it is recommended to be set to 80% of the hard limit of the memory limiter.

The port to use for exposing the collector’s own metrics as a prometheus endpoint. This can be used to resolve conflicting ports when a collector is using the host network.

Additional directory to mount in the node collector pod for logs. This is used to allow the collector to read logs from the host node if /var/log is symlinked to another directory.

Resources [memory/cpu] settings for the collectors group. these settings are used to protect the collectors instances from:

• running out of memory and being killed by the k8s OOM killer
• consuming all available memory on the node which can lead to node instability
• pushing back pressure to the instrumented applications

ServiceGraphEnabled is a feature that allows you to visualize the service graph of your application. It is enabled by default and can be disabled by setting the enabled flag to false.

Deprecated - use OtlpExporterConfiguration instead. EnableDataCompression is a feature that allows you to enable data compression before sending data to the Gateway collector. It is disabled by default and can be enabled by setting the enabled flag to true.

OtlpExporterConfiguration is the configuration for the OTLP exporter from node collector to cluster gateway collector.

ClusterMetricsEnabled is a feature that allows you to enable the cluster metrics. It is disabled by default and can be enabled by setting the enabled flag to true.

for destinations that uses https for exporting data, this value can be used to set the address for an https proxy. when unset or empty, no proxy will be used.

configuration for metrics handling in this collectors group if metric collection is disabled, this will be nil the content is populated only if relevant to this collectors group it’s being calculated based on active destinations and their settings, and global settings provided in the odigos configuration or instrumentation rules. it allows for the collector group reconciler to be simplified, and for visibility into the aggregated settings being used to derive configurations deployments and rollouts.

Node selector for the collectors group deployment. Use this to force the gateway to run only on nodes with specific labels. This is a hard requirement: the pod will be scheduled ONLY on nodes that match all labels. If no matching nodes exist, the pod will remain Pending.

Deployment name for the collectors group deployment. Only relevant for cluster gateway collector.

Receiver Signals are the signals (trace, metrics, logs) that the collector has setup an otlp receiver for, thus it can accept data from an upstream component. this is used to determine if a workload should export each signal or not. this list is calculated based on the odigos destinations that were configured

Represents the observations of a collectorsroup’s current state. Known .status.conditions.type are: “Available”, “Progressing”

The name of the container to which this configuration applies.

boolean flag to indicate if the agent should be enabled for this container.

An enum reason for the agent injection decision.

free text message to provide more information about the instrumentation decision. can be left empty if reason is self-explanatory.

set to true if the agent used in this container can be injected without pod manifest changes.

The name of the otel distribution to use for this container. if the name is empty, this container should not be instrumented.

Additional parameters to the distro that controls how it’s being applied. Keys are parameter names (like “libc”) and values are the value to use for that parameter (glibc / musl)

What method to use for injecting the agent environment variables (just those covered by the loader (PYTHONPATH, JAVA_TOOLS_OPTIONS, NODE_OPTIONS)) Can be either “loader” or “pod-manifest”. The injection should still check the actual values in the container manifest before injecting. Nil means that this container should not have env injection (agent should not be injected, or distro does not specify “loader” injection envs).

Each enabled signal must be set with a non-nil value (even if the config content is empty). nil means that the signal is disabled and should not be instrumented/collected by the agent.

The name of the container to which this configuration applies.

The sampling configuration that relevant for the collector (tailsampling).

The name of the container to override.

RuntimeInfo to use for agent enabling. If set for a container, the automatic detection will not be used for this container, and the distro to use will be calculated based on this value.

select one specific otel distro to use for this container. the selected distro must match the programming language and any constraints of the distro. if the programmin language is incorrect, the runtime info can be overridden to match

limit this rule to specific sources (by name, namespace, language, etc.) an empty list will match any source. if multiple items are set, the operation match if any one matches this relates to the “ResourceAttributes” part of a span.

limit this rule to specific operations. for example: specific endpoint or kafka topic. this field is optional, and if not set, the rule will be applied to all operations.

sampling percentage for cost reduction. this field is required. the final sampling percentage for traces that match this rule will be the highest possible, but at most this value.

optional free-form text field that allows you to attach notes for future context and maintenance. users can write why this rule was added, observations, document considerations, etc.

following settings enables/disables specific metric sources true - collect and send this metric source false - do not collect and send this metric source nil - use the default setting (from destination manifest, or cluster global setting)

MetricsSettings defines the metrics settings for this destination. ignored if destination does not support metrics or metrics are not enabled in signals

SourceSelector defines which sources can send data to this destination. If not specified, defaults to “all”.

Represents the observations of a destination’s current state.

Used as a fallback if all rules evaluate to false, it may be empty - in this case the default value will be 1 - all spans are sampled. it should be a float value in the range [0, 1] - the fraction of spans to sample. a value of 0 means no spans are sampled if none of the rules evaluate to true.

match server address exactly (e.g. collector.my.vendor.com)

match url path exactly (e.g. /api/v1/metrics)

match method exactly, can be empty to match any method

match route exactly

match preffix of route

match method exactly, can be empty to match any method

match http server operation (trace that starts with an http endpoint)

match http client operation (trace that starts with an http client operation) common for agents that are internally calling home over http, and exporting data.

Limit HTTP headers collection to specific header keys. if unset, no HTTP headers will be collected. HTTP headers cannot be collected as wildcard, to avoid leaking sensitive information.

limit the operation to specific sources. an empty list will match any source. if multiple items are set, the operation match if any one matches this relates to the “ResourceAttributes” part of a span.

if “Error” is set to true, only spans with SpanStatus set to “Error” are considered

if Duration is set, only operations with duration in milli seconds larger then this value are considered

optionally, limit this rule to specific operations. for example: specific endpoint or kafka topic. this field is optional, and if not set, the rule will be applied to all operations.

traces that contains this operation will be sampled by at least this percentage. if unset, 100% of such the traces will be sampled.

optional free-form text field that allows you to attach notes for future context and maintenance. users can write why this rule was added, observations, document considerations, etc.

a specific exact match http route

any route that starts with a specific prefix

optionally limit to specific http method

sourceId is a number between 0-255 (8 bits) written into the 8th byte of the trace id. if timedWall is specified, the sourceId is required.

the service.name property is used to populate the service.name resource attribute in the telemetry generated by this workload

determines if odigos should inject agents to pods of this workload.

true if all containers with agent injection enabled in this source can be enabled without pod manifest changes. if false, at least one container requires pod manifest changes to enable agent injection.

configuration for each instrumented container in the workload

will always list all containers of this workload by name, and override data in case it is configured on the source. this peoperty can be used to know all container names in the workload, even if other controllers did not yet run.

An hash of the containers overrides, used to determine if the overrides have changed for event filtering. this is updated only when the overrides are changed, and not when some other change in the source occurs.

this hash is used to determine the deployment of the agents. e.g. when the distro for container changes, or it’s compatibility version, or something else that requires rollout, the hash change will indicate that. if the hash is empty, it means that no agent should be enabled in any pod container.

The last time at which the agents meta hash value was changed. Pods created before this time may not be in alignment with the AgentsMetaHash. e.g. can lack the odigos label, or have a different value.

Configuration for the OpenTelemetry SDKs that this workload should use. The SDKs are identified by the programming language they are written in. TODO: consider adding more granular control over the SDKs, such as community/enterprise, native/ebpf.

Capture Runtime Details for the workloads that this CR applies to.

Represents the observations of a InstrumentationConfig’s current state.

This hash is recorded only after the rollout took place. it allows us to determine if the workload needs to be rollout based on previous rollout and the current config. if this field is different than the spec.AgentsDeploymentHash it means rollout is needed or not yet updated.

Check if rollback happened to an application

This time recorded only after the rollout took place. This allows us to determine whether a crashing application should be rolled back or not

Represents the status of odigos MANIFEST injection to existing pods template.

stores the name of the container in the pod where the SDK is running. The pod details can be found as the owner reference on the CR.

Attributes that identify the SDK and are reported as resource attributes in the generated telemetry. One can identify if an arbitrary telemetry is generated by this SDK by checking those resource attributes.

Attributes that are not reported as resource attributes but useful to describe characteristics of the SDK.

Healthy true means that the odigos agent has started the SDK, and there are no errors. User can expect telemetry to be generated. Healthy false means that the agent has stopped and telemetry data is not expected to be generated. Healthy nil means that the agent did not report any health status yet (prefer to always report health status).

message is a human readable message indicating details about the SDK general health. can be omitted if healthy is true

reason contains a programmatic identifier indicating the reason for the component status. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API.

code attributes configuration for a specific library. if not set, the default code attributes configuration for the workload will be used. if set, but internal fields are empty, those fields will be used from the default configuration.

Whether the instrumentation library is enabled to record traces. When false, it is expected that the instrumentation library does not produce any spans regardless of any other configuration. When true, the instrumentation library should produce spans according to the other configuration options. If not specified, the default value for this signal should be used (whether to enable libraries by default or not).

The name of the instrumentation library

• Node.js: The name of the npm package: @opentelemetry/instrumentation-<name>

SpanKind is only supported by Golang and will be ignored for any other SDK language. In Go, SpanKind is used because the same instrumentation library can be utilized for different span kinds (e.g., client/server).

for example (“net/http”, “@opentelemetry/instrumentation-redis”)

Attributes that identify the component. The combination of (Name, Type, IdentifyingAttributes) must be unique.

Attributes that do not necessarily identify the component but help describe its characteristics.

message is a human readable message indicating details about the component health. can be omitted if healthy is true

reason contains a programmatic identifier indicating the reason for the SDK status. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API.

Allows you to attach a meaningful name to the rule for convenience. Odigos does not use or assume any meaning from this field.

A free-form text field that allows you to attach notes regarding the rule for convenience. For example: why it was added. Odigos does not use or assume any meaning from this field.

A boolean field allowing to temporarily disable the rule, but keep it around for future use

An array of workload objects (name, namespace, kind) to which the rule should be applied. If not specified, the rule will be applied to all workloads. empty array will render the rule inactive.

For fine grained control, the user can specify the instrumentation library to use. One can specify same rule for multiple languages and libraries at the same time. If nil, all instrumentation libraries will be used. If empty, no instrumentation libraries will be used.

Allows to configure payload collection aspects for different types of payloads.

Deprecated: use OtelDistros instead.

Set the otel distros to use instead of the defaults.

Configure which code attributes should be recorded as span attributes.

Allows to configure the collection of http headers for different types of payloads.

Configure the tracing configuration for the library.

Add custom instrumentation probes

Configure general fraction of traces to record if none of the rules evaluate to true. this can help in reducing very noisy and heavy traffic services. note that traces will be dropped regardless of thier attributes/errors/importance. @deprecated: use odigos config to set this value instead.

Represents the observations of a instrumentationrule’s current state. Known .status.conditions.type are: “Available”, “Progressing”

the topic name to match. if left empty, all topics are matched.

limit this rule to specific sources (by name, namespace, language, etc.) for example: if “other agent” rule for noisty operation is relevant only in java, limit this rule by setting source scope to java and prevent other languages from being affected if the list is empty - all sources are matched.

limit this rule to specific operations. for example: specific http server endpoint (GET “/healthz” as an example). this field is optional, and if not set, the rule will be applied to all operations.

sampling percentage for noisy operations. if unset, 0% of such the traces will be collected. this percentage has “at most” semantics - the final sampling percentage for traces that match this rule will be the highest possible, but at most this value.

optional free-form text field that allows you to attach notes for future context and maintenance. users can write why this rule was added, observations, document considerations, etc.

if true, odigos will send all the metrics it collects about itself to the metrics pipeline, which will make them available to the metrics destinations. users can troubleshoot odigos itself by monitoring these metrics in their existing systems, and create their own dashboards, alerting, and more.

if true, odigos will send all the metrics it collects about itself to the odigos metrics store, which is available to odigos UI. it can help in presenting a consistent view of odigos itself, without relying on user system and integrations.

time interval for flusing metrics (format: 15s, 1m etc). defaults: 10s

if the source has any pods which are using the latest agent deployment setup.

if the source has any pods which are using an outdated agent deployment setup.

if the source has any pods which do not have the odigos agent injected.

type of the processor (batch, attributes, etc). this field is only the type, not it’s instance name in the collector configuration yaml

this name is solely for the user convenience, to attach a meaningful name to the processor. odigos must not assume any semantics from this name. odigos cannot assume this name is unique, not empty, exclude spaces or dots, limited in length, etc.

user can attach notes to the processor, to document its purpose, usage, etc.

disable is a flag to enable or disable the processor. if the processor is disabled, it will not be included in the collector configuration yaml. this allows the user to keep the processor configuration in the CR, but disable it temporarily.

signals can be used to control which observability signals are processed by the processor.

control which collector roles in odigos pipeline this processor is attached to.

control the order of processors. a processor with lower order hint value will be placed before other processors with higher value. if 2 processors have the same value, the order is arbitrary. if the value is missing (or 0) the processor can be placed anywhere in the pipeline

this it the configuration of the opentelemetry collector processor component with the type specified in ‘type’.

Indicates whether the target process is running is secure-execution mode. nil means we were unable to determine the secure-execution mode.

CriErrorMessage is set if the value in EnvFromContainerRuntime was not computed correctly and cannot be used safely. Sometimes, even if CRI check failed, it is possible to tell that relevant env vars are not coming from container runtime. Thus, this field is set only when there is:

• Actual CRI check failed
• The observed environment variables might come from container runtime

Holds the environment variables retrieved from the container runtime.

A temporary variable used during migration to track whether the new runtime detection process has been executed. If empty, it indicates the process has not yet been run. This field may be removed later.

give these sampling rules a name for display, easier identification and reference.

a free-form text field that allows you to attach notes regardinag the rule for convenience. Odigos does not use or assume any meaning from this field.

if set to true, the sampling rules will be disabled, they will not be taken into account for any sampling decisions. useful if you want to temporarily disable the rules but re-enable them later,

Represents the observations of a Sampling’s current state. Known .status.conditions.type are: “Available”, “Progressing”

The language of the SDK being configured

configurations for the instrumentation libraries the the SDK should use

HeadSamplingConfig is a set sampling rules. This config currently only applies to root spans. In the Future we might add another level of configuration base on the parent span (ParentBased Sampling)

default configuration for collecting code attributes, in case the instrumentation library does not provide a configuration.

default configuration for collecting http headers, in case the instrumentation library does not provide a configuration.

default configuration for library tracing.

list of the custom instrumentation probes the SDK should use.

configuration for runtime metrics that the SDK should generate. these are language-specific metrics like JVM metrics for Java, CLR metrics for .NET, etc.

If a namespace is specified, all workloads (sources) within that namespace are allowed to send data. Example: namespaces: [“default”, “production”] This means the destination will receive data from all sources in “default” and “production” namespaces.

Workloads (sources) are assigned to Datastreams via labels (odigos.io/data-stream: true), allowing a more flexible selection mechanism. Example: dataStreams: [“backend”, “monitoring”] This means the destination will receive data only from sources labeled with “backend” or “monitoring”.

Workload represents the workload or namespace to be instrumented. This field is required upon creation and cannot be modified.

DisableInstrumentation excludes this workload from auto-instrumentation.

OtelServiceName determines the “service.name” resource attribute which will be reported by the instrumentations of this source. If not set, the workload name will be used. It is not valid for namespace sources.

Specify specific override values for containers in a workload source. Not valid for namespace sources. Can be used to set the runtime info in case the automatic detection fails or produce wrong results. Containers are identified by their names. All containers not listed will retain their default behavior.

MatchWorkloadNameAsRegex indicates that the workload name should be matched using regex. When true, spec.workload.name is treated as a regular expression pattern. This allows matching multiple workloads with a single Source CRD. Not valid for namespace sources.

Represents the observations of a source’s current state. Known .status.conditions.type are: “Available”, “Progressing”

list of scope rules to be applied to the span name. all options are always tried, regardless of whether the previous options have matched or not.

the name of the opentelemetry intrumentation scope which the renamed spans are written in.

list of regex replacements to be applied to the span name. all options are always tried, regardless of whether the previous options have matched or not.

match http server operations in a generic way.

match kafka consumer operations (consume spans)

match kafka producer operations (produce spans)

Rule is the template rule to be applied to URLs