feat: Be explicit about span vs resource attributes

Author: andersliland

README.md

@@ -45,6 +45,15 @@ Troncos is designed to take advantage of `ddtrace` made by DataDog.
 
 The ddtrace docs can be found [here](https://ddtrace.readthedocs.io/en/stable/).
 
+[Best practices for traces](https://grafana.com/docs/tempo/latest/operations/best-practices/#naming-conventions-for-span-and-resource-attributes) is a good guide to get started.
+
+#### Span vs resource attributes
+
+- A `span attribute` is a key/value pair that provides context for its span.
+- A `resource attribute` is a key/value pair that describes the context of how the span was collected.
+
+For more information, read the [Attribute and Resource](https://opentelemetry.io/docs/specs/otel/overview/) sections in the OpenTelemetry specification.
+
 ### Enabling the tracer
 
 Configure ddtrace as usual and run `configure_tracer` to send spans to Tempo.
@@ -62,9 +71,10 @@ from troncos.tracing import configure_tracer
 
 # Configure tracer as described in the ddtrace docs.
 ddtrace.config.django["service_name"] = 'SERVICE_NAME'
+# These are added as span attributes
 ddtrace.tracer.set_tags(
     tags={
-        "fulfillment_center": 'osl2',
+        "key": "value",
     }
 )
 
@@ -78,6 +88,14 @@ configure_tracer(
     enabled=False, # Set to True when TRACE_HOST is configured.
     service_name='SERVICE_NAME',
     endpoint=f"http://{TRACE_HOST}:{TRACE_PORT}/v1/traces",
+    resource_attributes={
+        "app": "app",
+        "component": "component",
+        "role": "role",
+        "tenant": "tenant",
+        "owner": "owner",
+        "version": "version",
+    }
 )
 ```
 

tests/tracing/test_writer.py

@@ -12,15 +12,15 @@
 def tracer_test(
     httpserver: HTTPServer,
     service_name: str,
-    service_attributes: dict[str, Any] | None = None,
+    resource_attributes: dict[str, Any] | None = None,
 ) -> Generator[Tracer, Any, Any]:
     httpserver.expect_oneshot_request("/v1/trace").respond_with_data("OK")
 
     tracer = Tracer()
     tracer.configure(
         writer=OTELWriter(
             service_name=service_name,
-            service_attributes=service_attributes,
+            resource_attributes=resource_attributes,
             endpoint=httpserver.url_for("/v1/trace"),
             exporter=Exporter.HTTP,
         )
@@ -51,7 +51,7 @@ def test_attributes(httpserver: HTTPServer) -> None:
     with tracer_test(
         httpserver,
         "test_attributes",
-        service_attributes={"service_attribute": "working"},
+        resource_attributes={"resource_attribute": "working"},
     ) as tracer:
         with tracer.trace("test") as span:
             span.set_tag("span_attribute", "also_working")
@@ -82,7 +82,7 @@ def test_headers(httpserver: HTTPServer) -> None:
     tracer.configure(
         writer=OTELWriter(
             service_name="test_headers",
-            service_attributes={},
+            resource_attributes={},
             endpoint=httpserver.url_for("/v1/trace"),
             exporter=Exporter(
                 exporter_type=ExporterType.HTTP, headers={"test-header": "works"}

troncos/tracing/__init__.py

@@ -13,15 +13,15 @@ def configure_tracer(
     enabled: bool,
     endpoint: str,
     service_name: str,
-    service_attributes: dict[str, Any] | None = None,
+    resource_attributes: dict[str, Any] | None = None,
     exporter: Exporter = Exporter.HTTP,
 ) -> None:
     """Configure ddtrace to write traces to the otel tracing backend."""
 
     # Initialize our custom writer used to handle ddtrace spans.
     writer = OTELWriter(
         service_name=service_name,
-        service_attributes=service_attributes,
+        resource_attributes=resource_attributes,
         endpoint=endpoint,
         exporter=exporter,
     )

troncos/tracing/_writer.py

@@ -13,20 +13,20 @@ class OTELWriter(TraceWriter):
     def __init__(
         self,
         service_name: str,
-        service_attributes: dict[str, Any] | None,
+        resource_attributes: dict[str, Any] | None,
         endpoint: str,
         exporter: Exporter,
     ) -> None:
         self.service_name = service_name
-        self.service_attributes = service_attributes
+        self.resource_attributes = resource_attributes
         self.endpoint = endpoint
         self.exporter = exporter
 
         self.otel_span_processors = get_otel_span_processors(
             endpoint=endpoint, exporter=exporter
         )
         self.otel_default_resource = Resource.create(
-            {"service.name": service_name, **(service_attributes or {})}
+            {"service.name": service_name, **(resource_attributes or {})}
         )
         self.otel_ignore_attrs = (
             set(self.otel_default_resource.attributes.keys()) | default_ignore_attrs()
@@ -35,7 +35,7 @@ def __init__(
     def recreate(self) -> "OTELWriter":
         return self.__class__(
             self.service_name,
-            self.service_attributes,
+            self.resource_attributes,
             self.endpoint,
             exporter=self.exporter,
         )