ops[tracing] with a charm lib

Author: dimaqq

docs/howto/trace-the-charm-code.md

@@ -3,30 +3,15 @@
 
 ## Tracing from scratch
 
-FIXME: write this up
-
-- depend on `ops[tracing]`
-- remove charm\_tracing charm lib, if it's installed
-- observe the `SetupTracingEvent`
-
-```py
-class YourCharm(ops.CharmBase):
-    def __init__(self, framework: ops.Framework):
-        super().__init__(framework)
-        self.framework.observe(self.on.setup_tracing, self._on_setup_tracing)
-        ...
-
-    def _on_setup_tracing(self, event: ops.SetupTracingEvent) -> None:
-        # FIXME must get this from some relation
-        event.set_destination(url='http://localhost:4318/v1/traces')
-```
+FIXME: copy from tracing/api.py
 
 ## Migrating from charm\_tracing
 
 - depend on `ops[tracing]`
+- remove direct dependencies on `opentelemetry-api, -sdk, etc.`
 - remove charm\_tracing charm lib, if it's installed
 - remove `@trace_charm` decorator
-- observe the `SetupTracingEvent`
+- include `ops._tracing.Tracing()` in your charm's `__init__`
 - instrument key functions in the charm
 
 NOTE: charm\_tracing auto-instruments all public function on the class. `ops[tracing]` doesn't do that.

docs/requirements.txt

@@ -6,6 +6,8 @@
 #
 alabaster==1.0.0
     # via sphinx
+annotated-types==0.7.0
+    # via pydantic
 anyio==4.8.0
     # via
     #   starlette
@@ -101,12 +103,16 @@ opentelemetry-semantic-conventions==0.51b0
     #   opentelemetry-sdk
 opentelemetry-util-http==0.51b0
     # via opentelemetry-instrumentation-urllib
-otlp-json==0.9.4
+otlp-json==0.9.7
     # via ops (pyproject.toml)
 packaging==24.2
     # via
     #   opentelemetry-instrumentation
     #   sphinx
+pydantic==2.10.6
+    # via ops (pyproject.toml)
+pydantic-core==2.27.2
+    # via pydantic
 pygments==2.19.1
     # via
     #   furo
@@ -183,6 +189,8 @@ typing-extensions==4.12.2
     # via
     #   anyio
     #   opentelemetry-sdk
+    #   pydantic
+    #   pydantic-core
 uc-micro-py==1.0.3
     # via linkify-it-py
 urllib3==2.3.0

dont-merge/fake-charm.py

@@ -99,7 +99,6 @@
     'SecretExpiredEvent',
     'SecretRemoveEvent',
     'SecretRotateEvent',
-    'SetupTracingEvent',
     'StartEvent',
     'StopEvent',
     'StorageAttachedEvent',
@@ -246,7 +245,6 @@
     SecretExpiredEvent,
     SecretRemoveEvent,
     SecretRotateEvent,
-    SetupTracingEvent,
     StartEvent,
     StopEvent,
     StorageAttachedEvent,

dont-merge/metadata.yaml

@@ -491,7 +491,6 @@ def _make_framework(self, dispatcher: _Dispatcher):
 
     def _emit(self):
         """Emit the event on the charm."""
-        _charm._setup_tracing(self.charm)
         # TODO: Remove the collect_metrics check below as soon as the relevant
         #       Juju changes are made. Also adjust the docstring on
         #       EventBase.defer().
@@ -556,14 +555,11 @@ def main(charm_class: Type[_charm.CharmBase], use_juju_for_storage: Optional[boo
 
     See `ops.main() <#ops-main-entry-point>`_ for details.
     """
-    _tracing.setup_tracing(charm_class.__name__)
-
-    try:
-        with tracer.start_as_current_span('ops.main'):
-            manager = _Manager(charm_class, use_juju_for_storage=use_juju_for_storage)
+    with _tracing.setup_tracing(charm_class.__name__):
+        try:
+            with tracer.start_as_current_span('ops.main'):
+                manager = _Manager(charm_class, use_juju_for_storage=use_juju_for_storage)
 
             manager.run()
-    except _Abort as e:
-        sys.exit(e.exit_code)
-    finally:
-        _tracing.shutdown_tracing()
+        except _Abort as e:
+            sys.exit(e.exit_code)

dont-merge/readme.md

@@ -18,6 +18,9 @@
 
 from __future__ import annotations
 
+from contextlib import contextmanager
+from typing import Generator
+
 import opentelemetry.trace
 
 import ops.version
@@ -30,19 +33,18 @@
         mark_observed,
         set_tracing_destination,
         setup_tracing,
-        shutdown_tracing,
     )
 except ImportError:
 
     def mark_observed() -> None: ...
     def set_tracing_destination(*, url: str | None, ca: str | None = None) -> None: ...
-    def setup_tracing(charm_class_name: str) -> None: ...
-    def shutdown_tracing() -> None: ...
+    @contextmanager
+    def setup_tracing(charm_class_name: str) -> Generator[None, None, None]:
+        yield
 
 
 __all__ = [
     'mark_observed',
     'set_tracing_destination',
     'setup_tracing',
-    'shutdown_tracing',
 ]