settle on reousrce attributes, start on the docs

Author: dimaqq

docs/howto/index.md

@@ -24,6 +24,7 @@ Get started with charm testing <get-started-with-charm-testing>
 Write unit tests for a charm <write-scenario-tests-for-a-charm>
 Write integration tests for a charm <write-integration-tests-for-a-charm>
 Write legacy unit tests for a charm <write-unit-tests-for-a-charm>
+Trace the charm code <trace-the-charm-code>
 Turn a hooks-based charm into an ops charm <turn-a-hooks-based-charm-into-an-ops-charm>
 
 ```

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

@@ -0,0 +1,36 @@
+(trace-the-charm-code)=
+# Trace the charm code
+
+## 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')
+```
+
+## Migrating from charm\_tracing
+
+- depend on `ops[tracing]`
+- remove charm\_tracing charm lib, if it's installed
+- remove `@trace_charm` decorator
+- observe the `SetupTracingEvent`
+- instrument key functions in the charm
+
+NOTE: charm\_tracing auto-instruments all public function on the class. `ops[tracing]` doesn't do that.
+
+```py
+# FIXME example
+```

docs/reference/index.md

@@ -9,5 +9,6 @@ ops
 pebble
 ops-testing
 ops-testing-harness
+ops-tracing
 ```
 

docs/reference/ops-tracing.rst

@@ -0,0 +1,14 @@
+.. _ops_tracing:
+
+`ops[tracing]`, telemetry
+=========================
+
+FIXME: write this up.
+
+Open Telemetry resource attributes.
+
+- ``service.namespace`` the UUID of the Juju model.
+- ``service.namespace.name`` the name of the Juju model.
+- ``service.name`` the application name, like ``user_db``.
+- ``service.instance.id`` the unit number, like ``0``.
+- ``service.charm`` the charm class name, like ``DbCharm``.

ops/_tracing/buffer.py

@@ -17,6 +17,7 @@
 import functools
 import logging
 import sqlite3
+from pathlib import Path
 from typing import Callable
 
 from typing_extensions import ParamSpec, TypeVar
@@ -83,8 +84,8 @@ class Buffer:
     """Marks that data from this dispatch invocation has been marked observed."""
     stored: int | None = None
 
-    def __init__(self, path: str):
-        self.path = path
+    def __init__(self, path: Path | str):
+        self.path = str(path)
         self.ids = set()
         self._set_db_schema()
 

ops/_tracing/export.py

@@ -21,6 +21,7 @@
 import time
 import urllib.error
 import urllib.request
+from pathlib import Path
 from typing import Sequence
 
 # FIXME: single-file Python package can't be marked as py.typed
@@ -58,15 +59,15 @@
 
 
 # NOTE: OTEL SDK suppresses errors while exporting data
-# TODO: decide if we need to remove this before going to prod
+# FIXME: decide if we need to remove this before going to prod
 logger.addHandler(logging.StreamHandler())
 
 
 class ProxySpanExporter(SpanExporter):
     settings: tuple[str | None, str | None] = (None, None)
     cache: dict[str | None, ssl.SSLContext]
 
-    def __init__(self, buffer_path: str):
+    def __init__(self, buffer_path: Path | str):
         self.buffer = ops._tracing.buffer.Buffer(buffer_path)
         self.lock = threading.Lock()
         self.cache = {}
@@ -119,6 +120,11 @@ def ssl_context(self, ca: str | None) -> ssl.SSLContext:
     def _ssl_context(self, ca: str | None) -> ssl.SSLContext:
         # FIXME: What should our protocol range be?
         # this means TLS {v1, v1.1, v1.2}
+        # Do we need to set v1_2 or v1_3 explicitly?
+        # Py 3.10 update the secure cipher list
+        # Do we need to set ciphers explicitly for Py 3.8?
+        # We'd match https://wiki.mozilla.org/Security/Server_Side_TLS "Modern".
+        # FIXME SSLContext(args) or create_default_context(args)?
         context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
         # FIXME: we should probably allow ca=None
         # and then we'd pick up system or certifi certs?
@@ -165,7 +171,8 @@ def do_export(self, buffered_id: int, data: bytes, mime: str) -> None:
             # if it's the latter, the response test/JSON is helpful
             resp = e.fp.read()
             print('FIXME', e.code, str(resp)[:1000])
-        except (urllib.error.URLError, TimeoutError, ssl.SSLError):
+        except OSError:
+            # URLError, TimeoutError, SSLError, socket.error
             pass
         except Exception:
             logger.exception('Failed to send telemetry out')
@@ -200,62 +207,21 @@ def setup_tracing(charm_class_name: str) -> None:
     global _exporter
     # FIXME would it be better to pass Juju context explicitly?
     juju_context = ops.jujucontext._JujuContext.from_dict(os.environ)
-    app_name = '' if juju_context.unit_name is None else juju_context.unit_name.split('/')[0]
-    service_name = f'{app_name}-charm'  # only one COS charm sets custom value
+    # FIXME is it ever possible for unit_name to be unset (empty)?
+    app_name, unit_number = juju_context.unit_name.split('/', 1)
 
     resource = Resource.create(
         attributes={
-            # https://opentelemetry.io/docs/languages/sdk-configuration/general/
-            # https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource#semantic-attributes-with-dedicated-environment-variable
-            #
-            # TODO:
-            # service.namespace: model uuid, because that's globally unique
-            # (find some field): model name, human-readable
-            # service.name: unit name (?)
-            # service.instance.id: /etc/machine-id (set for vms, empty for k8s)
-            # (these follow Juju topology by Simme)
-            #
-            # alternatively, one could argue that:
-            # service.name: app name
-            # (some field): unit name
-            # - could abuse instance id, though that's not what it's for
-            #
-            # alternatively still:
-            # service.namespace: model uuid
-            # service.name: charm name (perhaps not app name?)
-            # service.instance.id: unit name?
-            #
-            # OTEL defines some standard-ish attributes:
-            # service.name        required
-            # service.instance.id recommended
-            # service.namespace   recommended -- maybe model name?
-            # service.version     recommended
-            #
-            # FIXME: this is quite important, I think
-            # because we're setting the stage for future Juju telemetry
-            # ideally we'd agree what these fields mean for the end users
-            # to have a consistent view over their deployment.
-            'service.name': charm_class_name,
+            # TODO: document these
             'service.namespace': juju_context.model_uuid,
-            'service.instance.id': juju_context.unit_name,
-            # charm lib tags
-            'compose_service': service_name,  # FIXME why is this copy needed?
-            'charm_type': charm_class_name,
-            # these may not be needed if included in service.xxx
-            # Following same attribute names as charm_tracing lib
-            # FIXME: decide if it makes sense
-            'juju_unit': juju_context.unit_name,
-            'juju_application': app_name,
-            'juju_model': juju_context.model_name,
-            'juju_model_uuid': juju_context.model_uuid,
+            'service.namespace.name': juju_context.model_name,
+            'service.name': app_name,
+            'service.instance.id': unit_number,
+            'service.charm': charm_class_name,
         }
     )
     provider = TracerProvider(resource=resource)
-
-    # How
-
-    buffer_path = str(juju_context.charm_dir / BUFFER_FILE)
-    _exporter = ProxySpanExporter(buffer_path)
+    _exporter = ProxySpanExporter(juju_context.charm_dir / BUFFER_FILE)
     span_processor = BatchSpanProcessor(_exporter)
     provider.add_span_processor(span_processor)
     set_tracer_provider(provider)