---
title: Charmhub | Deploy OpenTelemetry Collector Integrator using Charmhub - The Open
  Operator Collection
description: Deploy the latest version of OpenTelemetry Collector Integrator on any
  cloud.
url: https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator
---

# OpenTelemetry Collector Integrator

[Jose Massón](https://charmhub.io/publisher/jose-masson "View all packages from Jose Massón")

* [Jose Massón](https://charmhub.io/publisher/jose-masson "View all packages from Jose Massón")

Platform:

26.04

24.04

22.04

3.0/stable 8

```
juju deploy opentelemetry-collector-integrator --channel 3.0/stable
```

[Learn to deploy on juju >](https://juju.is/docs/juju/manage-applications)

[Toggle side navigation](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#drawer)

## charms.opentelemetry\_collector\_integrator.v0.opentelemetry\_collector\_integrator

* [*Docstrings*Docstrings](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator)
  [*Code*Source code](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator/source-code)
* + Download

    Fetch library

    ```
    charmcraft fetch-lib charms.opentelemetry_collector_integrator.v0.opentelemetry_collector_integrator
    ```

    [Download opentelemetry\_collector\_integrator.py](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator/download)
  + *Last updated* 06 Apr 2026
  + *Revision* Library version 0.1

OpentelemetryCollectoIntegrator charm library.

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

##### Overview

This library provides four main components:

* **OtelcolIntegratorProviderAppData**: Data model for validation
* **OtelcolIntegratorProviderRelationUpdater**: Provider-side relation updates
* **OtelcolIntegratorRequirer**: Requirer-side configuration retrieval
* **SecretURI**: Secret URI validation and parsing utilities

##### Usage

###### Provider Side (Sharing Configuration)

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

```
from charms.opentelemetry_collector_integrator.v0.opentelemetry_collector_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.opentelemetry_collector_integrator.v0.opentelemetry_collector_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>`

  + Validated using the `SecretURI` class, which can also be used directly for custom validation
  + 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.

##### Advanced Usage

###### Direct Secret URI Validation

For advanced use cases, you can work with secret URIs directly:

```
from charms.opentelemetry_collector_integrator.v0.opentelemetry_collector_integrator import SecretURI

# Parse and use a secret URI
secret = SecretURI.from_uri("secret://model-uuid/secret-id/key?render=inline")
print(secret.base_secret_id)  # secret://model-uuid/secret-id
print(secret.key)             # key
print(secret.render)          # inline

# Just validate without parsing (raises ValueError/ValidationError if invalid)
SecretURI.validate_uri("secret://model-uuid/secret-id/key?render=file")
```

##### 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)
```

---

Index

* [class Pipeline](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#pipeline)
* [class SecretURI](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#secreturi)
* + [def from\_uri(
    cls,
    uri)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#secreturi-from_uri)
* + [def validate\_uri(
    cls,
    uri)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#secreturi-validate_uri)
* + [def base\_secret\_id(
    self)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#secreturi-base_secret_id)
* + [def \_\_str\_\_(
    self)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#secreturi-__str__)
* [class OtelcolIntegratorProviderAppData](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#otelcolintegratorproviderappdata)
* + [def validate\_yaml(
    cls,
    v)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#otelcolintegratorproviderappdata-validate_yaml)
* + [def validate\_pipelines(
    cls,
    v)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#otelcolintegratorproviderappdata-validate_pipelines)
* [class OtelcolIntegratorProviderRelationUpdater](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#otelcolintegratorproviderrelationupdater)
* + [def update\_relations\_data(
    application,
    relations,
    data)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#otelcolintegratorproviderrelationupdater-update_relations_data)
* [class OtelcolIntegratorRequirer](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#otelcolintegratorrequirer)
* + [def \_\_init\_\_(
    self,
    model,
    relation\_name,
    secrets\_dir)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#otelcolintegratorrequirer-__init__)
* + [def secret\_files(
    self)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#otelcolintegratorrequirer-secret_files)
* + [def retrieve\_external\_configs(
    self)](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#otelcolintegratorrequirer-retrieve_external_configs)
* [def extract\_secret\_uris(
  config\_yaml
  )](https://charmhub.io/opentelemetry-collector-integrator/libraries/opentelemetry_collector_integrator#extract_secret_uris)

#### class Pipeline

Description

OpenTelemetry Collector pipeline types. None

#### class SecretURI

Represents a validated Juju secret URI with key and render mode.

Attributes

model\_uuid

The Juju model UUID.

secret\_id

The Juju secret ID.

key

The key within the secret to access.

render

How to render the secret ('inline' or 'file').

Description

Format: secret://<model-uuid>/<secret-id>/<key>?render=<inline|file>

This class encapsulates the validation logic for secret URIs used in
OpenTelemetry Collector configurations. It ensures that secret references
are well-formed and contain all required components.

Methods

SecretURI.
from\_uri(

cls

,
uri: str
)

Parse and validate a secret URI string.

Arguments

uri

Secret URI string to parse.

Returns

Validated SecretURI instance.

SecretURI.
validate\_uri(

cls

,
uri: str
)

Validate a secret URI format and values.

Arguments

uri

Secret URI string to validate.

Description

Use this when you only need to validate a URI without using the parsed object.

SecretURI.
base\_secret\_id(

*self*
)

Base secret ID without key or query parameters.

Returns

Base secret URI (secret://<model-uuid>/<secret-id>).

SecretURI.
\_\_str\_\_(

*self*
)

Convert back to URI string format.

Returns

The secret URI as a string.

#### class OtelcolIntegratorProviderAppData

Model representing data shared through external-config relation.

Attributes

config\_yaml

OpenTelemetry Collector YAML configuration.

secret\_ids

Set of Juju secret URIs referenced in the configuration.

pipelines

List of enabled pipeline names (metrics, logs, traces).

Methods

OtelcolIntegratorProviderAppData.
validate\_yaml(

cls

,
v: str
)

Validate that config\_yaml is valid YAML and secret URIs have correct format.

Arguments

v

The config\_yaml string to validate.

Returns

The validated config\_yaml string.

OtelcolIntegratorProviderAppData.
validate\_pipelines(

cls

,
v
)

Validate pipelines list is not empty.

Arguments

v

List of pipelines to validate.

Returns

The validated list of pipelines.

#### class OtelcolIntegratorProviderRelationUpdater

Description

Updates relation data for Otelcol integrator provider relations. None

Methods

OtelcolIntegratorProviderRelationUpdater.
update\_relations\_data(

application: Application

,
relations

,
data: OtelcolIntegratorProviderAppData
)

Update relation data with validated configuration.

Arguments

application

The application object to use for relation data.

relations

List of relations to update.

data

Validated relation data model.

#### class OtelcolIntegratorRequirer

Requirer side (e.g. otelcol) of the external-config relation.

Description

This class is used by charms that consume configuration from
opentelemetry-collector-integrator via the external-config relation.

Methods

OtelcolIntegratorRequirer.
\_\_init\_\_(

*self*

,
model: Model

,
relation\_name: str

,
secrets\_dir: str
)

Initialize the requirer with the Juju model.

Arguments

model

The Juju model to use for resolving secrets.

relation\_name

Name of the relation to use.

secrets\_dir

Directory where secret files should be stored.

OtelcolIntegratorRequirer.
secret\_files(

*self*
)

Description

Get mapping of file paths to secret content for file-based secrets. None

OtelcolIntegratorRequirer.
retrieve\_external\_configs(

*self*
)

Retrieve the config\_yaml from the external-config relation.

Arguments

relations

List of relations to extract configurations from.

Returns

List of dictionaries containing config\_yaml and pipelines.
Secret URIs in config\_yaml are replaced with actual values.
Invalid relation data is skipped with a warning.

#### def extract\_secret\_uris(config\_yaml: str)

Extract base secret URIs (without keys) from the config YAML.

Arguments

config\_yaml

YAML configuration text that may contain secret URIs

Returns

Set of unique base secret URIs (secret://model-uuid/secret-id)

Description

Searches for secret URIs in the format: secret://model-uuid/secret-id