Migration guide: from `charm_tracing` to `ops[tracing]`

doc
,
1

charm_tracing, your trusted charm library for autoinstrumenting charm code and submitting charm traces to a distributed tracing backend such as Tempo is being deprecated, and replaced by less cowboy-coded, even more trusted native ops functionality.

Deprecation timeline:

  • now, we’ve released a v0.8 that pops a friendly deprecation warning
  • next cycle (25.10) we’ll release a v0.9 that raises a not-so-friendly exception

Luckily, migrating the base functionality isn’t difficult.

Before

If you were using charm_tracing, your charm likely looked something like this:

# charmcraft.yaml
[...]

requires:
  charm-tracing:
    interface: tracing
  certificates:
    interface: tls-certificates

# charm.py

from charms.tempo_coordinator_k8s.v0.charm_tracing import trace_charm
from charms.tempo_coordinator_k8s.v0.tracing import TracingEndpointRequirer, charm_tracing_config

@trace_charm(
    tracing_endpoint="_charm_tracing_endpoint",
    server_cert="_charm_tracing_cert",
    extra_types=[TempoWorker],
)
class Foo(CharmBase):
    def __init__(...):
            self.charm_tracing = TracingEndpointRequirer(
                self, relation  _name="charm-tracing", protocols=["otlp_http"]
            )
        self._charm_tracing_endpoint, self._charm_tracing_cert = charm_tracing_config(
            self.charm_tracing, Path("/path/to/cacert")
        )

After

In order to switch over to ops[tracing], you will have to make the following changes:

# charmcraft.yaml
[...]

requires:
  charm-tracing:
    interface: tracing
  receive-ca-cert:
    interface: certificate_transfer

# charm.py

from ops.tracing import Tracing

class Foo(CharmBase):
    def __init__(...):
            self.tracing = Tracing(
                tracing_relation_name='charm-tracing', 
                ca_relation_name='receive-ca-cert'
            )

This means you can delete the charm_tracing charm lib and remove any direct dependencies you had on opentelemetry-exporter-otlp-proto-http, as that is now baked into ops[tracing]. You also don’t need the tracing or certificate-exchange charm libs (unless you’re using them directly in other ways as well!), because they too are baked into ops[tracing].

(Auto)Instrumentation changes

The good news is that ops is now natively instrumented and gives much better traces at all external IO endpoints (hook tool calls & pebble calls), as well at the charm event interface (every event fired on the charm has its own span).

The less good news is that the charm_tracing autoinstrumentation behaviour that automatically created a span for each public method on the charm class (and other objects you could point it to) is now gone for good.

The good news is that you can relatively easily use otel’s python sdk to manually instrument your critical paths. (Or write your own autoinstrumentation wrapper (or probably even somehow keep using or copy-pasta the one from the charm_tracing library), but you didn’t hear that from me.)

1 Like