feat: Tracing. (#33)

* feat: Tracing.

* feat: Add integration with opentelemetry.

* fix: update tests

* chore: add tests

---------

Co-authored-by: Noah Hummel <[email protected]>

Author: yeldiRium

eventsourcingdb_client_python/event/event.py

@@ -1,6 +1,7 @@
 from datetime import datetime
 from typing import TypeVar
 
+from .tracing import TracingContext
 from ..errors.validation_error import ValidationError
 from .event_context import EventContext
 
@@ -18,7 +19,8 @@ def __init__(
         event_id: str,
         time: datetime,
         data_content_type: str,
-        predecessor_hash: str
+        predecessor_hash: str,
+        tracing_context: TracingContext = None
     ):
         super().__init__(
             source,
@@ -28,7 +30,8 @@ def __init__(
             event_id,
             time,
             data_content_type,
-            predecessor_hash
+            predecessor_hash,
+            tracing_context
         )
         self.data = data
 
@@ -50,7 +53,8 @@ def parse(unknown_object: dict) -> Self:
             event_context.event_id,
             event_context.time,
             event_context.data_content_type,
-            event_context.predecessor_hash
+            event_context.predecessor_hash,
+            event_context.tracing_context
         )
 
     def to_json(self):

eventsourcingdb_client_python/event/event_candidate.py

@@ -1,5 +1,6 @@
 from dataclasses import dataclass
 
+from .tracing import TracingContext
 from .validate_subject import validate_subject
 from .validate_type import validate_type
 
@@ -10,15 +11,21 @@ class EventCandidate:
     subject: str
     type: str
     data: dict
+    tracing_context: TracingContext | None = None
 
     def validate(self) -> None:
         validate_subject(self.subject)
         validate_type(self.type)
 
     def to_json(self):
-        return {
+        json = {
             'data': self.data,
             'source': self.source,
             'subject': self.subject,
             'type': self.type
         }
+
+        if self.tracing_context is not None:
+            json['tracingContext'] = self.tracing_context.to_json()
+
+        return json

eventsourcingdb_client_python/event/event_context.py

@@ -2,6 +2,7 @@
 from datetime import datetime
 from typing import TypeVar
 
+from .tracing import TracingContext
 from ..errors.internal_error import InternalError
 from ..errors.validation_error import ValidationError
 from .validate_subject import validate_subject
@@ -20,6 +21,7 @@ class EventContext:
     time: datetime
     data_content_type: str
     predecessor_hash: str
+    tracing_context: TracingContext | None = None
 
     @staticmethod
     def parse(unknown_object: dict) -> Self:
@@ -75,6 +77,11 @@ def parse(unknown_object: dict) -> Self:
             raise ValidationError(
                 f'Failed to parse predecessor_hash \'{predecessor_hash}\' to string.')
 
+        raw_tracing_context = unknown_object.get("tracingContext")
+        tracing_context = TracingContext.parse(raw_tracing_context) \
+            if raw_tracing_context is not None \
+            else None
+
         return EventContext(
             source=source,
             subject=subject,
@@ -83,7 +90,8 @@ def parse(unknown_object: dict) -> Self:
             event_id=event_id,
             time=time,
             data_content_type=data_content_type,
-            predecessor_hash=predecessor_hash
+            predecessor_hash=predecessor_hash,
+            tracing_context=tracing_context
         )
 
     def to_json(self):

eventsourcingdb_client_python/event/source.py

@@ -1,6 +1,7 @@
 from dataclasses import dataclass
 
 from eventsourcingdb_client_python.event.event_candidate import EventCandidate
+from eventsourcingdb_client_python.event.tracing import TracingContext
 
 
 @dataclass
@@ -11,6 +12,7 @@ def new_event(
         self,
         subject: str,
         event_type: str,
-        data: dict
+        data: dict,
+        tracing_context: TracingContext = None
     ) -> EventCandidate:
-        return EventCandidate(self.source, subject, event_type, data)
+        return EventCandidate(self.source, subject, event_type, data, tracing_context)

eventsourcingdb_client_python/event/tracing.py

@@ -0,0 +1,82 @@
+from dataclasses import dataclass
+from typing import TypeVar
+
+from opentelemetry.trace import TraceState, TraceFlags, SpanContext, format_trace_id, format_span_id
+
+from ..errors.validation_error import ValidationError
+
+Self = TypeVar("Self", bound="TracingContext")
+
+
+@dataclass
+class TracingContext:
+    trace_id: str
+    span_id: str
+    trace_flags: TraceFlags = TraceFlags.DEFAULT
+    trace_state: TraceState = TraceState()
+
+    @staticmethod
+    def from_span_context(span_context: SpanContext) -> Self:
+        return TracingContext(
+            trace_id=format_trace_id(span_context.trace_id),
+            span_id=format_span_id(span_context.span_id),
+            trace_flags=span_context.trace_flags,
+            trace_state=span_context.trace_state
+        )
+
+    def trace_flags_to_string(self) -> str:
+        return format(self.trace_flags, "02x")
+
+    def trace_parent(self) -> str:
+        return f'00-{self.trace_id}-{self.span_id}-{self.trace_flags_to_string()}'
+
+    def to_opentelemetry_context_carrier(self):
+        return {
+            'traceparent': self.trace_parent(),
+            'tracestate': self.trace_state.to_header()
+        }
+
+    @staticmethod
+    def parse(unknown_object: dict) -> Self:
+        trace_id = unknown_object.get("traceId")
+        if not isinstance(trace_id, str):
+            raise ValidationError(
+                f'Failed to parse trace id \'{trace_id}\' to string.')
+
+        span_id = unknown_object.get("spanId")
+        if not isinstance(span_id, str):
+            raise ValidationError(
+                f'Failed to parse span id \'{span_id}\' to string.')
+
+        raw_trace_flags = unknown_object.get("traceFlags")
+        if not isinstance(raw_trace_flags, str):
+            raise ValidationError(
+                f'Failed to parse trace flags \'{raw_trace_flags}\' to string.')
+        if raw_trace_flags == format(TraceFlags.DEFAULT, "02x"):
+            trace_flags = TraceFlags.DEFAULT
+        elif raw_trace_flags == format(TraceFlags.SAMPLED, "02x"):
+            trace_flags = TraceFlags.SAMPLED
+        else:
+            raise ValidationError(
+                'Trace flags must be either None (0) or Sampled (1).')
+
+        raw_trace_state = unknown_object.get("traceState")
+        if not isinstance(raw_trace_state, str):
+            raise ValidationError(
+                f'Failed to parse trace state \'{raw_trace_state}\' to string.')
+        trace_state = TraceState.from_header([raw_trace_state])
+
+        return TracingContext(
+            trace_id=trace_id,
+            span_id=span_id,
+            trace_flags=trace_flags,
+            trace_state=trace_state
+        )
+
+    def to_json(self):
+        return {
+            'traceId': self.trace_id,
+            'spanId': self.span_id,
+            'traceFlags': self.trace_flags_to_string(),
+            'traceState': self.trace_state.to_header()
+        }