lmnr 0.4.62__tar.gz → 0.4.64__tar.gz

{lmnr-0.4.62 → lmnr-0.4.64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lmnr
-Version: 0.4.62
+Version: 0.4.64
 Summary: Python SDK for Laminar
 License: Apache-2.0
 Author: lmnr.ai

{lmnr-0.4.62 → lmnr-0.4.64}/pyproject.toml

@@ -6,7 +6,7 @@
 
 [project]
 name = "lmnr"
-version = "0.4.62"
+version = "0.4.64"
 description = "Python SDK for Laminar"
 authors = [
   { name = "lmnr.ai", email = "founders@lmnr.ai" }

{lmnr-0.4.62 → lmnr-0.4.64}/src/lmnr/__init__.py

@@ -10,6 +10,7 @@ from .sdk.types import (
     TracingLevel,
 )
 from .sdk.decorators import observe
+from .sdk.types import LaminarSpanContext
 from .openllmetry_sdk import Instruments
 from .openllmetry_sdk.tracing.attributes import Attributes
 from opentelemetry.trace import use_span

{lmnr-0.4.62 → lmnr-0.4.64}/src/lmnr/openllmetry_sdk/__init__.py

@@ -76,3 +76,8 @@ class Traceloop:
             project_api_key=project_api_key,
             max_export_batch_size=max_export_batch_size,
         )
+
+    @staticmethod
+    def flush():
+        if Traceloop.__tracer_wrapper:
+            Traceloop.__tracer_wrapper.flush()

{lmnr-0.4.62 → lmnr-0.4.64}/src/lmnr/openllmetry_sdk/tracing/tracing.py

@@ -38,7 +38,7 @@ from opentelemetry.sdk.trace.export import (
     SimpleSpanProcessor,
     BatchSpanProcessor,
 )
-from opentelemetry.trace import get_tracer_provider, ProxyTracerProvider
+from opentelemetry.sdk.trace import SpanLimits
 
 from typing import Dict, Optional, Set
 
@@ -69,6 +69,8 @@ EXCLUDED_URLS = """
     githubusercontent.com,
     openaipublic.blob.core.windows.net"""
 
+MAX_EVENTS_OR_ATTRIBUTES_PER_SPAN = 5000
+
 
 class TracerWrapper(object):
     resource_attributes: dict = {}
@@ -291,22 +293,21 @@ def init_spans_exporter(api_endpoint: str, headers: Dict[str, str]) -> SpanExpor
         )
 
 
+# TODO: check if it's safer to use the default tracer provider obtained from
+# get_tracer_provider()
 def init_tracer_provider(resource: Resource) -> TracerProvider:
-    provider: TracerProvider = None
-    default_provider: TracerProvider = get_tracer_provider()
-
-    if isinstance(default_provider, ProxyTracerProvider):
-        provider = TracerProvider(resource=resource)
-        trace.set_tracer_provider(provider)
-    elif not hasattr(default_provider, "add_span_processor"):
-        module_logger.error(
-            "Cannot add span processor to the default provider since it doesn't support it"
-        )
-        return
-    else:
-        provider = default_provider
+    tracer_provider = TracerProvider(
+        resource=resource,
+        span_limits=SpanLimits(
+            # this defaults to 128, which causes us to drop messages
+            max_attributes=MAX_EVENTS_OR_ATTRIBUTES_PER_SPAN,
+            max_span_attributes=MAX_EVENTS_OR_ATTRIBUTES_PER_SPAN,
+            max_event_attributes=MAX_EVENTS_OR_ATTRIBUTES_PER_SPAN,
+            max_events=MAX_EVENTS_OR_ATTRIBUTES_PER_SPAN,
+        ),
+    )
 
-    return provider
+    return tracer_provider
 
 
 def init_instrumentations(

{lmnr-0.4.62 → lmnr-0.4.64}/src/lmnr/sdk/laminar.py

@@ -13,7 +13,6 @@ from lmnr.openllmetry_sdk.config import MAX_MANUAL_SPAN_PAYLOAD_SIZE
 from lmnr.openllmetry_sdk.decorators.base import json_dumps
 from opentelemetry import context as context_api, trace
 from opentelemetry.context import attach, detach
-from lmnr.version import SDK_VERSION, get_latest_pypi_version, is_latest_version
 from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
     OTLPSpanExporter,
     Compression,
@@ -36,6 +35,7 @@ import requests
 import re
 import urllib.parse
 import uuid
+import warnings
 
 from lmnr.openllmetry_sdk.tracing.attributes import (
     SESSION_ID,
@@ -55,6 +55,7 @@ from .types import (
     InitEvaluationResponse,
     EvaluationResultDatapoint,
     GetDatapointsResponse,
+    LaminarSpanContext,
     PipelineRunError,
     PipelineRunResponse,
     NodeInput,
@@ -347,8 +348,10 @@ class Laminar:
             Literal["DEFAULT"], Literal["LLM"], Literal["TOOL"]
         ] = "DEFAULT",
         context: Optional[Context] = None,
-        trace_id: Optional[uuid.UUID] = None,
         labels: Optional[dict[str, str]] = None,
+        parent_span_context: Optional[LaminarSpanContext] = None,
+        # deprecated, use parent_span_context instead
+        trace_id: Optional[uuid.UUID] = None,
     ):
         """Start a new span as the current span. Useful for manual
         instrumentation. If `span_type` is set to `"LLM"`, you should report
@@ -371,11 +374,21 @@ class Laminar:
                 and response attributes manually. Defaults to "DEFAULT".
             context (Optional[Context], optional): raw OpenTelemetry context\
                 to attach the span to. Defaults to None.
-            trace_id (Optional[uuid.UUID], optional): [EXPERIMENTAL] override\
-                the trace id for the span. If not provided, use the current\
-                trace id. Defaults to None.
+            parent_span_context (Optional[LaminarSpanContext], optional): parent\
+                span context to use for the span. Useful for continuing traces\
+                across services. If parent_span_context is a\
+                raw OpenTelemetry span context, or if it is a dictionary or string\
+                obtained from `Laminar.get_laminar_span_context_dict()` or\
+                `Laminar.get_laminar_span_context_str()` respectively, it will be\
+                converted to a `LaminarSpanContext` if possible. See also\
+                `Laminar.get_span_context`, `Laminar.get_span_context_dict` and\
+                `Laminar.get_span_context_str` for more information.
+                Defaults to None.
             labels (Optional[dict[str, str]], optional): labels to set for the\
                 span. Defaults to None.
+            trace_id (Optional[uuid.UUID], optional): [Deprecated] override\
+                the trace id for the span. If not provided, use the current\
+                trace id. Defaults to None.
         """
 
         if not cls.is_initialized():
@@ -385,21 +398,29 @@ class Laminar:
         with get_tracer() as tracer:
             ctx = context or context_api.get_current()
             if trace_id is not None:
-                if isinstance(trace_id, uuid.UUID):
-                    span_context = trace.SpanContext(
-                        trace_id=int(trace_id),
-                        span_id=random.getrandbits(64),
-                        is_remote=False,
-                        trace_flags=trace.TraceFlags(trace.TraceFlags.SAMPLED),
-                    )
-                    ctx = trace.set_span_in_context(
-                        trace.NonRecordingSpan(span_context), ctx
-                    )
-                else:
-                    cls.__logger.warning(
-                        "trace_id provided to `Laminar.start_as_current_span`"
-                        " is not a valid UUID"
-                    )
+                warnings.warn(
+                    "trace_id provided to `Laminar.start_as_current_span`"
+                    " is deprecated, use parent_span_context instead",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            if parent_span_context is not None:
+                span_context = LaminarSpanContext.try_to_otel_span_context(
+                    parent_span_context, cls.__logger
+                )
+                ctx = trace.set_span_in_context(
+                    trace.NonRecordingSpan(span_context), ctx
+                )
+            elif trace_id is not None and isinstance(trace_id, uuid.UUID):
+                span_context = trace.SpanContext(
+                    trace_id=int(trace_id),
+                    span_id=random.getrandbits(64),
+                    is_remote=False,
+                    trace_flags=trace.TraceFlags(trace.TraceFlags.SAMPLED),
+                )
+                ctx = trace.set_span_in_context(
+                    trace.NonRecordingSpan(span_context), ctx
+                )
             ctx_token = attach(ctx)
             label_props = {}
             try:
@@ -487,8 +508,10 @@ class Laminar:
             Literal["DEFAULT"], Literal["LLM"], Literal["TOOL"]
         ] = "DEFAULT",
         context: Optional[Context] = None,
-        trace_id: Optional[uuid.UUID] = None,
+        parent_span_context: Optional[LaminarSpanContext] = None,
         labels: Optional[dict[str, str]] = None,
+        # deprecated, use parent_span_context instead
+        trace_id: Optional[uuid.UUID] = None,
     ):
         """Start a new span. Useful for manual instrumentation.
         If `span_type` is set to `"LLM"`, you should report usage and response
@@ -530,30 +553,48 @@ class Laminar:
                 and response attributes manually. Defaults to "DEFAULT".
             context (Optional[Context], optional): raw OpenTelemetry context\
                 to attach the span to. Defaults to None.
-            trace_id (Optional[uuid.UUID], optional): [EXPERIMENTAL] override\
-                the trace id for the span. If not provided, use the current\
-                trace id. Defaults to None.
+            parent_span_context (Optional[LaminarSpanContext], optional): parent\
+                span context to use for the span. Useful for continuing traces\
+                across services. If parent_span_context is a\
+                raw OpenTelemetry span context, or if it is a dictionary or string\
+                obtained from `Laminar.get_laminar_span_context_dict()` or\
+                `Laminar.get_laminar_span_context_str()` respectively, it will be\
+                converted to a `LaminarSpanContext` if possible. See also\
+                `Laminar.get_span_context`, `Laminar.get_span_context_dict` and\
+                `Laminar.get_span_context_str` for more information.
+                Defaults to None.
             labels (Optional[dict[str, str]], optional): labels to set for the\
                 span. Defaults to None.
+            trace_id (Optional[uuid.UUID], optional): Deprecated, use\
+                `parent_span_context` instead. If provided, it will be used to\
+                set the trace id for the span.
         """
         with get_tracer() as tracer:
             ctx = context or context_api.get_current()
             if trace_id is not None:
-                if isinstance(trace_id, uuid.UUID):
-                    span_context = trace.SpanContext(
-                        trace_id=int(trace_id),
-                        span_id=random.getrandbits(64),
-                        is_remote=False,
-                        trace_flags=trace.TraceFlags(trace.TraceFlags.SAMPLED),
-                    )
-                    ctx = trace.set_span_in_context(
-                        trace.NonRecordingSpan(span_context), ctx
-                    )
-                else:
-                    cls.__logger.warning(
-                        "trace_id provided to `Laminar.start_span`"
-                        " is not a valid UUID"
-                    )
+                warnings.warn(
+                    "trace_id provided to `Laminar.start_span`"
+                    " is deprecated, use parent_span_context instead",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            if parent_span_context is not None:
+                span_context = LaminarSpanContext.try_to_otel_span_context(
+                    parent_span_context, cls.__logger
+                )
+                ctx = trace.set_span_in_context(
+                    trace.NonRecordingSpan(span_context), ctx
+                )
+            elif trace_id is not None and isinstance(trace_id, uuid.UUID):
+                span_context = trace.SpanContext(
+                    trace_id=int(trace_id),
+                    span_id=random.getrandbits(64),
+                    is_remote=False,
+                    trace_flags=trace.TraceFlags(trace.TraceFlags.SAMPLED),
+                )
+                ctx = trace.set_span_in_context(
+                    trace.NonRecordingSpan(span_context), ctx
+                )
             label_props = {}
             try:
                 if labels:
@@ -688,6 +729,77 @@ class Laminar:
             else:
                 span.set_attribute(key.value, value)
 
+    @classmethod
+    def get_laminar_span_context(
+        cls, span: Optional[trace.Span] = None
+    ) -> Optional[LaminarSpanContext]:
+        """Get the laminar span context for a given span.
+        If no span is provided, the current active span will be used.
+        """
+        span = span or trace.get_current_span()
+        if span == trace.INVALID_SPAN:
+            return None
+        return LaminarSpanContext(
+            trace_id=uuid.UUID(int=span.get_span_context().trace_id),
+            span_id=uuid.UUID(int=span.get_span_context().span_id),
+            is_remote=span.get_span_context().is_remote,
+        )
+
+    @classmethod
+    def get_laminar_span_context_dict(
+        cls, span: Optional[trace.Span] = None
+    ) -> Optional[dict]:
+        """Get the laminar span context for a given span as a dictionary.
+        If no span is provided, the current active span will be used.
+
+        This is useful for continuing a trace across services.
+
+        Example:
+        ```python
+        # service A:
+        with Laminar.start_as_current_span("service_a"):
+            span_context = Laminar.get_laminar_span_context_dict()
+            # send span_context to service B
+            call_service_b(request, headers={"laminar-span-context": span_context})
+
+        # service B:
+        def call_service_b(request, headers):
+            span_context = LaminarSpanContext.from_dict(headers["laminar-span-context"])
+            with Laminar.start_as_current_span("service_b", parent_span_context=span_context):
+                # rest of the function
+                pass
+        ```
+
+        This will result in a trace like:
+        ```
+        service_a
+          service_b
+        ```
+        """
+        span_context = cls.get_laminar_span_context(span)
+        if span_context is None:
+            return None
+        return span_context.to_dict()
+
+    @classmethod
+    def get_laminar_span_context_str(
+        cls, span: Optional[trace.Span] = None
+    ) -> Optional[str]:
+        span_context = cls.get_laminar_span_context(span)
+        if span_context is None:
+            return None
+        return json.dumps(span_context.to_dict())
+
+    @classmethod
+    def deserialize_laminar_span_context(
+        cls, span_context: Union[dict, str]
+    ) -> LaminarSpanContext:
+        return LaminarSpanContext.deserialize(span_context)
+
+    @classmethod
+    def shutdown(cls):
+        Traceloop.flush()
+
     @classmethod
     def set_session(
         cls,

{lmnr-0.4.62 → lmnr-0.4.64}/src/lmnr/sdk/types.py

@@ -1,6 +1,9 @@
+import logging
 import aiohttp
 import datetime
 from enum import Enum
+import json
+from opentelemetry.trace import SpanContext, TraceFlags
 import pydantic
 from typing import Any, Awaitable, Callable, Optional, Union
 import uuid
@@ -210,3 +213,86 @@ class TracingLevel(Enum):
     OFF = 0
     META_ONLY = 1
     ALL = 2
+
+
+class LaminarSpanContext(pydantic.BaseModel):
+    """
+    A span context that can be used to continue a trace across services. This
+    is a slightly modified version of the OpenTelemetry span context. For
+    usage examples, see `Laminar.get_laminar_span_context_dict`,
+    `Laminar.get_laminar_span_context_str`, `Laminar.get_span_context`, and
+    `Laminar.deserialize_laminar_span_context`.
+
+    The difference between this and the OpenTelemetry span context is that
+    the `trace_id` and `span_id` are stored as UUIDs instead of integers for
+    easier debugging, and the separate trace flags are not currently stored.
+    """
+
+    trace_id: uuid.UUID
+    span_id: uuid.UUID
+    is_remote: bool = pydantic.Field(default=False)
+
+    # uuid is not serializable by default, so we need to convert it to a string
+    def to_dict(self):
+        return {
+            "traceId": str(self.trace_id),
+            "spanId": str(self.span_id),
+            "isRemote": self.is_remote,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "LaminarSpanContext":
+        return cls(
+            trace_id=uuid.UUID(data["traceId"]),
+            span_id=uuid.UUID(data["spanId"]),
+            is_remote=data["isRemote"],
+        )
+
+    @classmethod
+    def try_to_otel_span_context(
+        cls,
+        span_context: Union["LaminarSpanContext", dict[str, Any], str, SpanContext],
+        logger: Optional[logging.Logger] = None,
+    ) -> SpanContext:
+        if logger is None:
+            logger = logging.getLogger(__name__)
+
+        if isinstance(span_context, LaminarSpanContext):
+            return SpanContext(
+                trace_id=span_context.trace_id.int,
+                span_id=span_context.span_id.int,
+                is_remote=span_context.is_remote,
+                trace_flags=TraceFlags(TraceFlags.SAMPLED),
+            )
+        elif isinstance(span_context, SpanContext) or (
+            isinstance(getattr(span_context, "trace_id", None), int)
+            and isinstance(getattr(span_context, "span_id", None), int)
+        ):
+            logger.warning(
+                "span_context provided"
+                " is likely a raw OpenTelemetry span context. Will try to use it. "
+                "Please use `LaminarSpanContext` instead."
+            )
+            return span_context
+        elif isinstance(span_context, dict) or isinstance(span_context, str):
+            try:
+                laminar_span_context = cls.deserialize(span_context)
+                return SpanContext(
+                    trace_id=laminar_span_context.trace_id.int,
+                    span_id=laminar_span_context.span_id.int,
+                    is_remote=laminar_span_context.is_remote,
+                    trace_flags=TraceFlags(TraceFlags.SAMPLED),
+                )
+            except Exception:
+                raise ValueError("Invalid span_context provided")
+        else:
+            raise ValueError("Invalid span_context provided")
+
+    @classmethod
+    def deserialize(cls, data: Union[dict[str, Any], str]) -> "LaminarSpanContext":
+        if isinstance(data, dict):
+            return cls.from_dict(data)
+        elif isinstance(data, str):
+            return cls.from_dict(json.loads(data))
+        else:
+            raise ValueError("Invalid span_context provided")

{lmnr-0.4.62 → lmnr-0.4.64}/src/lmnr/version.py

@@ -3,7 +3,7 @@ import requests
 from packaging import version
 
 
-SDK_VERSION = "0.4.62"
+SDK_VERSION = "0.4.64"
 PYTHON_VERSION = f"{sys.version_info.major}.{sys.version_info.minor}"