OpenTelemetry Collector Integrator

OtelcolIntegrator charm library.

This library provides utilities for integrating with the Otelcol Integrator Charm through the external-config relation. It supports sharing configuration and secrets between charms.

Overview

This library provides three main components:

• OtelcolIntegratorProviderAppData: Data model for validation
• OtelcolIntegratorProviderRelationUpdater: Provider-side relation updates
• OtelcolIntegratorRequirer: Requirer-side configuration retrieval

Usage

Provider Side (Sharing Configuration)

Use this side when your charm provides OpenTelemetry Collector configuration to other charms.

from charms.otelcol_integrator.v0.otelcol_integrator import (
    OtelcolIntegratorProviderAppData,
    OtelcolIntegratorProviderRelationUpdater,
    Pipeline,
)

1. Create and validate your configuration data

config_data = OtelcolIntegratorProviderAppData(
    config_yaml='''
exporters:
  splunk_hec:
    token: "secret://model-uuid/secret-id/token?render=inline"
    endpoint: "https://splunk:8088/services/collector"
    ''',
    pipelines=[Pipeline.METRICS, Pipeline.LOGS]
)

2. Update all relations with the configuration

relations = self.model.relations.get("external-config", [])
OtelcolIntegratorProviderRelationUpdater.update_relations_data(
    application=self.app,
    relations=relations,
    data=config_data
)

Secret URI Format:

• Inline secrets: secret://model-uuid/secret-id/key?render=inline
• File-based secrets: secret://model-uuid/secret-id/key?render=file

Requirer Side (Consuming Configuration)

Use this side when your charm consumes OpenTelemetry Collector configuration from another charm.

from charms.otelcol_integrator.v0.otelcol_integrator import (
    OtelcolIntegratorRequirer,
    Pipeline,
)

1. Initialize the requirer

self.requirer = OtelcolIntegratorRequirer(
    model=self.model,
    relation_name="external-config",
    secrets_dir="/etc/otelcol/secrets"  # Where secret files should go
)

2. Retrieve configurations from all relations

configs = self.requirer.retrieve_external_configs()

configs is a list of dicts:

[
    {
        "config_yaml": "...",  # Secrets resolved to values or paths
        "pipelines": [Pipeline.METRICS, Pipeline.LOGS]  # List of Pipeline enums
    }
]

3. Write secret files to disk

After calling retrieve_external_configs(), the library tracks all file-based secrets (those with render=file) in the secret_files property:

# Retrieve configs (this populates secret_files automatically)
configs = self.requirer.retrieve_external_configs()

# Access the tracked secret files
# secret_files is a Dict[str, str] mapping file paths to content
for file_path, content in self.requirer.secret_files.items():
    # Create parent directories if needed
    Path(file_path).parent.mkdir(parents=True, exist_ok=True)

    # Write the secret content to disk
    Path(file_path).write_text(content, mode=0o644)

Important Notes:

• The library does NOT write files to disk automatically
• It tracks file paths and content in the secret_files property
• The charm is responsible for actually writing the files
• Secret URIs with render=inline are embedded directly in config_yaml
• Secret URIs with render=file are replaced with paths in config_yaml and tracked in secret_files

Data Validation

The OtelcolIntegratorProviderAppData model automatically validates:

• config_yaml: Must be valid YAML

• Secret URIs: Must follow format secret://<model-uuid>/<secret-id>/<key>?render=<inline|file>

  • Note that if render=inline, the key's value will be embedded directly in the config, on the other hand if render=file a filepath will be generated and the secret content will be tracked for writing by the charm.

• pipelines: List of Pipeline enum values (Pipeline.METRICS, Pipeline.LOGS, Pipeline.TRACES)

Invalid data will raise a ValidationError with a descriptive message.

Examples

Provider with Inline Secret

# The secret token will be fetched and embedded directly in the config
config_data = OtelcolIntegratorProviderAppData(
    config_yaml='''
receivers:
  prometheus:
    config:
      scrape_configs:
        - bearer_token: "secret://model-uuid/secret-id/token?render=inline"
    ''',
    pipelines=[Pipeline.METRICS]
)

Provider with File-based Secret

# The secret will be written to a file, path replaces the URI
config_data = OtelcolIntegratorProviderAppData(
    config_yaml='''
exporters:
  otlp:
    tls:
      cert_file: "secret://model-uuid/secret-id/cert?render=file"
      key_file: "secret://model-uuid/secret-id/key?render=file"
    ''',
    pipelines=[Pipeline.TRACES]
)

Requirer Processing Multiple Relations

# Get configs from all related charms
configs = self.requirer.retrieve_external_configs()

# Merge or process each config
for config in configs:
    yaml_config = yaml.safe_load(config["config_yaml"])
    pipelines = config["pipelines"]  # List[Pipeline] enums

    # Convert to strings if needed
    pipeline_names = [p.value for p in pipelines]

    # Process configuration...
    # Note: config_yaml already has file-based secrets replaced with paths

# Write secret files to disk (for all relations)
# secret_files contains all file-based secrets from retrieve_external_configs()
for file_path, content in self.requirer.secret_files.items():
    Path(file_path).parent.mkdir(parents=True, exist_ok=True)
    Path(file_path).write_text(content)