Skip to main content

​
Considerations

Before configuring Head Sampling Fallback Fraction, please note the following:
  • This rule applies to traces that don’t match any specific head sampling rules (e.g., health checks)
  • Traces will be dropped regardless of their attributes, errors, or importance
  • Setting a low fraction can significantly reduce trace volume and costs, but may also drop important traces
  • This is useful for high-traffic services where you want to sample most traces while keeping specific rules for important traces

​
Configuration Options

fractionToKeep float : Controls what fraction of traces should be kept when none of the head sampling rules evaluate to true.
  • This field is optional, and defaults to 1 (all traces are kept)
  • Valid range: 0 to 1 (inclusive)
  • 0 means no traces will be recorded unless they matched a specific rule to keep
  • 1 (default) means all traces will be recorded
  • Values between 0 and 1 will sample that fraction of traces (e.g., 0.1 keeps 10% of traces)
If fractionToKeep is not specified, it defaults to 1, meaning all traces will be recorded unless they match a specific head sampling rule (like health checks).

​
Basic Example

The following example demonstrates how to configure a fallback fraction to sample 10% of traces that don’t match any specific head sampling rules.
1
Create a YAML file with the following content:
head-sampling-fallback.yaml
apiVersion: odigos.io/v1alpha1
kind: InstrumentationRule
metadata:
  name: head-sampling-fallback
  namespace: odigos-system
spec:
  ruleName: "sample 10% of non-matching traces"
  headSamplingFallbackFraction:
    fractionToKeep: 0.1
2
Apply the rule to the cluster:
kubectl apply -f head-sampling-fallback.yaml

​
Example: Apply to a Single Workload

The following example demonstrates how to apply the fallback fraction rule to a specific workload:
head-sampling-fallback-workload.yaml
apiVersion: odigos.io/v1alpha1
kind: InstrumentationRule
metadata:
  name: head-sampling-fallback-workload
  namespace: odigos-system
spec:
  ruleName: "sample 10% of non-matching traces for deployment {deployment_name}"
  workloads:
    - namespace: {namespace}
      kind: Deployment
      name: {deployment_name}
  headSamplingFallbackFraction:
    fractionToKeep: 0.1 # only applies to single deployment above
This configuration will:
  • Apply the fallback fraction rule only to specifc Deployment by it’s name and namespace
  • Keep only 10% of traces that don’t match any specific head sampling rules for this workload

​
Notes

  • This feature is currently supported in agents that support head sampling: nodejs-community and nodejs-enterprise.
  • When multiple rules specify headSamplingFallbackFraction, the maximum value is used.
  • The fallback fraction only applies to traces that don’t match any specific head sampling rules (like health check rules).