jararaca 0.3.26__py3-none-any.whl → 0.3.29__py3-none-any.whl

jararaca/__init__.py

@@ -18,12 +18,20 @@ if TYPE_CHECKING:
         use_app_type,
     )
     from jararaca.observability.decorators import TracedClass, TracedFunc, traced_class
+    from jararaca.observability.fastapi_exception_handler import (
+        setup_fastapi_exception_handler,
+    )
     from jararaca.observability.hooks import (
         add_event,
+        add_span_link,
+        get_current_span,
+        get_current_span_context,
         get_tracing_provider,
         record_exception,
+        set_span_attribute,
         set_span_status,
         spawn_trace,
+        start_span,
     )
     from jararaca.observability.interceptor import ObservabilityInterceptor
     from jararaca.observability.providers.otel import OtelObservabilityProvider
@@ -233,8 +241,14 @@ if TYPE_CHECKING:
         "TracedFunc",
         "TracedClass",
         "traced_class",
+        "start_span",
+        "add_span_link",
+        "get_current_span",
+        "get_current_span_context",
         "spawn_trace",
+        "set_span_attribute",
         "add_event",
+        "setup_fastapi_exception_handler",
         "set_span_status",
         "record_exception",
         "get_tracing_provider",
@@ -412,6 +426,16 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
     "TracedClass": (__SPEC_PARENT__, "observability.decorators", None),
     "traced_class": (__SPEC_PARENT__, "observability.decorators", None),
     "spawn_trace": (__SPEC_PARENT__, "observability.hooks", None),
+    "setup_fastapi_exception_handler": (
+        __SPEC_PARENT__,
+        "observability.fastapi_exception_handler",
+        None,
+    ),
+    "set_span_attribute": (__SPEC_PARENT__, "observability.hooks", None),
+    "start_span": (__SPEC_PARENT__, "observability.hooks", None),
+    "add_span_link": (__SPEC_PARENT__, "observability.hooks", None),
+    "get_current_span": (__SPEC_PARENT__, "observability.hooks", None),
+    "get_current_span_context": (__SPEC_PARENT__, "observability.hooks", None),
     "add_event": (__SPEC_PARENT__, "observability.hooks", None),
     "set_span_status": (__SPEC_PARENT__, "observability.hooks", None),
     "record_exception": (__SPEC_PARENT__, "observability.hooks", None),

jararaca/observability/constants.py

@@ -0,0 +1,3 @@
+TRACEPARENT_KEY = "traceparent"
+
+__all__ = ["TRACEPARENT_KEY"]

jararaca/observability/decorators.py

@@ -35,9 +35,15 @@ AttributeValue = Union[
 AttributeMap = Mapping[str, AttributeValue]
 
 
+class TracingSpan(Protocol): ...
+
+
+class TracingSpanContext(Protocol): ...
+
+
 class TracingContextProvider(Protocol):
 
-    def start_trace_context(
+    def start_span_context(
         self, trace_name: str, context_attributes: AttributeMap | None
     ) -> ContextManager[Any]: ...
 
@@ -56,6 +62,19 @@ class TracingContextProvider(Protocol):
         escaped: bool = False,
     ) -> None: ...
 
+    def set_span_attribute(
+        self,
+        key: str,
+        value: AttributeValue,
+    ) -> None: ...
+
+    def update_span_name(self, new_name: str) -> None: ...
+
+    def add_link(self, span_context: TracingSpanContext) -> None: ...
+
+    def get_current_span(self) -> TracingSpan | None: ...
+    def get_current_span_context(self) -> TracingSpanContext | None: ...
+
 
 class TracingContextProviderFactory(Protocol):
 
@@ -117,7 +136,7 @@ class TracedFunc:
         ) -> Any:
 
             if ctx_provider := get_tracing_ctx_provider():
-                with ctx_provider.start_trace_context(
+                with ctx_provider.start_span_context(
                     self.trace_name,
                     self.trace_mapper(*args, **kwargs),
                 ):

jararaca/observability/fastapi_exception_handler.py

@@ -0,0 +1,33 @@
+from fastapi import FastAPI, Request, Response
+from fastapi.exception_handlers import (
+    http_exception_handler,
+    request_validation_exception_handler,
+)
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
+
+from jararaca.observability.constants import TRACEPARENT_KEY
+
+
+def setup_fastapi_exception_handler(
+    app: FastAPI, trace_header_name: str = "traceparent"
+) -> None:
+    async def base_http_exception_handler(
+        request: Request, exc: HTTPException | RequestValidationError
+    ) -> JSONResponse | Response:
+
+        if isinstance(exc, RequestValidationError):
+            response = await request_validation_exception_handler(request, exc)
+            response.headers[trace_header_name] = request.scope.get(TRACEPARENT_KEY, "")
+            return response
+        else:
+            err_response = await http_exception_handler(request, exc)
+
+            err_response.headers[trace_header_name] = request.scope.get(
+                TRACEPARENT_KEY, ""
+            )
+            return err_response
+
+    app.exception_handlers[HTTPException] = base_http_exception_handler
+    app.exception_handlers[RequestValidationError] = base_http_exception_handler

jararaca/observability/hooks.py

@@ -1,21 +1,25 @@
+import logging
 from contextlib import contextmanager
 from typing import Any, Generator, Literal
 
 from jararaca.observability.decorators import (
     AttributeMap,
+    AttributeValue,
     TracingContextProvider,
+    TracingSpan,
+    TracingSpanContext,
     get_tracing_ctx_provider,
 )
 
 
 @contextmanager
-def spawn_trace(
+def start_span(
     name: str,
     attributes: AttributeMap | None = None,
 ) -> Generator[None, Any, None]:
 
     if trace_context_provider := get_tracing_ctx_provider():
-        with trace_context_provider.start_trace_context(
+        with trace_context_provider.start_span_context(
             trace_name=name, context_attributes=attributes
         ):
             yield
@@ -23,6 +27,19 @@ def spawn_trace(
         yield
 
 
+def spawn_trace(
+    name: str,
+    attributes: AttributeMap | None = None,
+) -> None:
+    logging.warning(
+        "spawn_trace is deprecated, use start_span as context manager instead."
+    )
+    if trace_context_provider := get_tracing_ctx_provider():
+        trace_context_provider.start_span_context(
+            trace_name=name, context_attributes=attributes
+        )
+
+
 def add_event(
     name: str,
     attributes: AttributeMap | None = None,
@@ -55,5 +72,37 @@ def record_exception(
         )
 
 
+def set_span_attribute(
+    key: str,
+    value: AttributeValue,
+) -> None:
+
+    if trace_context_provider := get_tracing_ctx_provider():
+        trace_context_provider.set_span_attribute(
+            key=key,
+            value=value,
+        )
+
+
 def get_tracing_provider() -> TracingContextProvider | None:
     return get_tracing_ctx_provider()
+
+
+def get_current_span_context() -> TracingSpanContext | None:
+
+    if trace_context_provider := get_tracing_ctx_provider():
+        return trace_context_provider.get_current_span_context()
+    return None
+
+
+def get_current_span() -> TracingSpan | None:
+
+    if trace_context_provider := get_tracing_ctx_provider():
+        return trace_context_provider.get_current_span()
+    return None
+
+
+def add_span_link(span_context: TracingSpanContext) -> None:
+
+    if trace_context_provider := get_tracing_ctx_provider():
+        trace_context_provider.add_link(span_context=span_context)

jararaca/observability/providers/otel.py

@@ -34,23 +34,39 @@ from jararaca.microservice import (
     Microservice,
     use_app_transaction_context,
 )
+from jararaca.observability.constants import TRACEPARENT_KEY
 from jararaca.observability.decorators import (
     AttributeMap,
+    AttributeValue,
     TracingContextProvider,
     TracingContextProviderFactory,
+    TracingSpan,
+    TracingSpanContext,
 )
 from jararaca.observability.interceptor import ObservabilityProvider
 
 tracer: trace.Tracer = trace.get_tracer(__name__)
 
 
+class OtelTracingSpan(TracingSpan):
+
+    def __init__(self, span: trace.Span) -> None:
+        self.span = span
+
+
+class OtelTracingSpanContext(TracingSpanContext):
+
+    def __init__(self, span_context: trace.SpanContext) -> None:
+        self.span_context = span_context
+
+
 class OtelTracingContextProvider(TracingContextProvider):
 
     def __init__(self, app_context: AppTransactionContext) -> None:
         self.app_context = app_context
 
     @contextmanager
-    def start_trace_context(
+    def start_span_context(
         self,
         trace_name: str,
         context_attributes: AttributeMap | None,
@@ -82,6 +98,27 @@ class OtelTracingContextProvider(TracingContextProvider):
         span = trace.get_current_span()
         span.record_exception(exception, attributes=attributes, escaped=escaped)
 
+    def set_span_attribute(self, key: str, value: AttributeValue) -> None:
+        span = trace.get_current_span()
+        span.set_attribute(key, value)
+
+    def update_span_name(self, new_name: str) -> None:
+        span = trace.get_current_span()
+
+        span.update_name(new_name)
+
+    def add_link(self, span_context: TracingSpanContext) -> None:
+        if not isinstance(span_context, OtelTracingSpanContext):
+            return
+        span = trace.get_current_span()
+        span.add_link(span_context.span_context)
+
+    def get_current_span(self) -> TracingSpan | None:
+        return OtelTracingSpan(trace.get_current_span())
+
+    def get_current_span_context(self) -> TracingSpanContext | None:
+        return OtelTracingSpanContext(trace.get_current_span().get_span_context())
+
 
 class OtelTracingContextProviderFactory(TracingContextProviderFactory):
 
@@ -185,10 +222,15 @@ class OtelTracingContextProviderFactory(TracingContextProviderFactory):
             },
         ) as root_span:
             cx = root_span.get_span_context()
+            span_traceparent_id = hex(cx.trace_id)[2:].rjust(32, "0")
             if app_tx_ctx.transaction_data.context_type == "http":
-                app_tx_ctx.transaction_data.response.headers["traceparent"] = hex(
-                    cx.trace_id
-                )[2:].rjust(32, "0")
+                app_tx_ctx.transaction_data.request.scope[TRACEPARENT_KEY] = (
+                    span_traceparent_id
+                )
+            elif app_tx_ctx.transaction_data.context_type == "websocket":
+                app_tx_ctx.transaction_data.websocket.scope[TRACEPARENT_KEY] = (
+                    span_traceparent_id
+                )
             tracing_headers: ImplicitHeaders = {}
             TraceContextTextMapPropagator().inject(tracing_headers)
             W3CBaggagePropagator().inject(tracing_headers)

{jararaca-0.3.26.dist-info → jararaca-0.3.29.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: jararaca
-Version: 0.3.26
+Version: 0.3.29
 Summary: A simple and fast API framework for Python
 Home-page: https://github.com/LuscasLeo/jararaca
 Author: Lucas S

{jararaca-0.3.26.dist-info → jararaca-0.3.29.dist-info}/RECORD

@@ -1,7 +1,7 @@
 LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
 README.md,sha256=YmCngjU8llW0l7L3tuXkkfr8qH7V9aBMgfp2jEzeiKg,3517
-pyproject.toml,sha256=JXte3h2WM1G5riLSBoE2nBXWnybbJhqtoFl-N6Vt3ZI,2739
-jararaca/__init__.py,sha256=zQRbt5BrXFVvJW8pKaA9_KdkGFB6Njmr-9SyX0ZfenM,23331
+pyproject.toml,sha256=onnmUnr1FXl1m5F5BLHvwPeJjoQrCzetXPaqxh7F2Ao,2739
+jararaca/__init__.py,sha256=LH6u63yz8UTABwH4EMSrOprxw6Szn0nQWJB5A9U4VjY,24259
 jararaca/__main__.py,sha256=-O3vsB5lHdqNFjUtoELDF81IYFtR-DSiiFMzRaiSsv4,67
 jararaca/broker_backend/__init__.py,sha256=GzEIuHR1xzgCJD4FE3harNjoaYzxHMHoEL0_clUaC-k,3528
 jararaca/broker_backend/mapper.py,sha256=vTsi7sWpNvlga1PWPFg0rCJ5joJ0cdzykkIc2Tuvenc,696
@@ -26,11 +26,13 @@ jararaca/messagebus/message.py,sha256=U6cyd2XknX8mtm0333slz5fanky2PFLWCmokAO56vv
 jararaca/messagebus/publisher.py,sha256=JTkxdKbvxvDWT8nK8PVEyyX061vYYbKQMxRHXrZtcEY,2173
 jararaca/messagebus/worker.py,sha256=DiKDUhcU4rEjjA_3KqCmnN3X5yyokZq_-SbLryjS_PM,69237
 jararaca/microservice.py,sha256=DW4RVeqgrx4J-dAg17sbzTn_sLXuvV1UOQFde2fpqds,11471
-jararaca/observability/decorators.py,sha256=xTt4HEmpm_m1OUS29kaoZLMCT2YYToJUzQziepl8qfQ,6062
-jararaca/observability/hooks.py,sha256=vQCxb5m4uFse0lJIAuzSd84acu7iGDNgf4kpaWYkju8,1499
+jararaca/observability/constants.py,sha256=quhqXBjDWVrr8Vr3tglgYo7zsQyz_y-z_dtqfUzYaa8,63
+jararaca/observability/decorators.py,sha256=1mxIhBduikOYayq-cW9Pq1hbTzztUkjx0uzKJSSMEU4,6511
+jararaca/observability/fastapi_exception_handler.py,sha256=jSLhuR5Og3vRnIoZucRA5jPnvR6DEsM1ax7tQuEo5rc,1264
+jararaca/observability/hooks.py,sha256=RRv5q57bRurOUR4AIZpl1K07j9tSduj6LrBNc4xwfRs,2778
 jararaca/observability/interceptor.py,sha256=U4ZLM0f8j6Q7gMUKKnA85bnvD-Qa0ii79Qa_X8KsXAQ,1498
 jararaca/observability/providers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-jararaca/observability/providers/otel.py,sha256=DCNjGhcpF-XdlGTiYoQg9F_1ftcggTItDfJ_PjlZm0s,10808
+jararaca/observability/providers/otel.py,sha256=08G1-dHzckKo9DQiteJl8KUukH_5tL31b2YrTDEnuDA,12262
 jararaca/persistence/base.py,sha256=xnGUbsLNz3gO-9iJt-Sn5NY13Yc9-misP8wLwQuGGoM,1024
 jararaca/persistence/exports.py,sha256=Ghx4yoFaB4QVTb9WxrFYgmcSATXMNvrOvT8ybPNKXCA,62
 jararaca/persistence/interceptors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -76,8 +78,8 @@ jararaca/tools/typescript/interface_parser.py,sha256=VBx-TYQPjAiHLiYgzGdRl_p4xDb
 jararaca/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 jararaca/utils/rabbitmq_utils.py,sha256=ytdAFUyv-OBkaVnxezuJaJoLrmN7giZgtKeet_IsMBs,10918
 jararaca/utils/retry.py,sha256=DzPX_fXUvTqej6BQ8Mt2dvLo9nNlTBm7Kx2pFZ26P2Q,4668
-jararaca-0.3.26.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-jararaca-0.3.26.dist-info/METADATA,sha256=tQ8LaLhplQLYw8LPWadDAQ-lJw7Air5NCI_UGhAN550,5149
-jararaca-0.3.26.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-jararaca-0.3.26.dist-info/entry_points.txt,sha256=WIh3aIvz8LwUJZIDfs4EeH3VoFyCGEk7cWJurW38q0I,45
-jararaca-0.3.26.dist-info/RECORD,,
+jararaca-0.3.29.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+jararaca-0.3.29.dist-info/METADATA,sha256=SF-nYBMhJ-gK7OxaQ3Y75sVExlh7vCcyldV5hWT1NBg,5149
+jararaca-0.3.29.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+jararaca-0.3.29.dist-info/entry_points.txt,sha256=WIh3aIvz8LwUJZIDfs4EeH3VoFyCGEk7cWJurW38q0I,45
+jararaca-0.3.29.dist-info/RECORD,,

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "jararaca"
-version = "0.3.26"
+version = "0.3.29"
 description = "A simple and fast API framework for Python"
 authors = ["Lucas S <me@luscasleo.dev>"]
 readme = "README.md"