instrumentation-sdk 1.7.0__tar.gz

instrumentation_sdk-1.7.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: instrumentation-sdk
+Version: 1.7.0
+Summary: LLM Observability Instrumentation SDK
+Author: LLM Observability Team
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tiktoken>=0.5.0
+Requires-Dist: PyYAML>=6.0.0
+Requires-Dist: confluent-kafka>=2.3.0
+Requires-Dist: protobuf>=4.25.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: opentelemetry-api>=1.24.0
+Requires-Dist: opentelemetry-sdk>=1.24.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.24.0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.45b0
+Requires-Dist: opentelemetry-exporter-prometheus>=0.45b0
+Requires-Dist: pytest-asyncio>=0.23.0

instrumentation_sdk-1.7.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "instrumentation-sdk"
+version = "1.7.0"
+description = "LLM Observability Instrumentation SDK"
+authors = [
+    { name = "LLM Observability Team" }
+]
+dependencies = [
+    "pydantic>=2.0.0",
+    "tiktoken>=0.5.0",
+    "PyYAML>=6.0.0",
+    "confluent-kafka>=2.3.0",
+    "protobuf>=4.25.0",
+    "fastapi>=0.110.0",
+    "httpx>=0.27.0",
+    "opentelemetry-api>=1.24.0",
+    "opentelemetry-sdk>=1.24.0",
+    "opentelemetry-exporter-otlp>=1.24.0",
+    "opentelemetry-instrumentation-fastapi>=0.45b0",
+    "opentelemetry-exporter-prometheus>=0.45b0",
+    "pytest-asyncio>=0.23.0",
+]
+
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "performance: marks tests as load/performance tests (deselect with '-m not performance')",
+]

instrumentation_sdk-1.7.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

instrumentation_sdk-1.7.0/src/__init__.py

@@ -0,0 +1,39 @@
+from .features.spans import llm_observe, SpanReporter
+from .features.manual_instrumentation import llm_span
+from .features.spans.globals import set_reporter, get_reporter
+from .features.auto_instrumentation import (
+    init_auto_instrumentation,
+    uninstrument_all,
+    instrument_client,
+    instrument_http_client,
+    detect_llm_call,
+    trigger_test_call
+)
+from .features.token_counting import count_tokens, llm_span_with_tokens
+from .features.streaming import llm_streaming_span, wrap_stream, wrap_async_stream
+from .features.pii_injection_scan import scan_prompt
+from .features.metrics import init_metrics_pipeline, record_span_metrics
+from .features.deterministic_sampling import should_sample
+
+__all__ = [
+    "llm_observe",
+    "llm_span",
+    "set_reporter",
+    "get_reporter",
+    "SpanReporter",
+    "init_auto_instrumentation",
+    "uninstrument_all",
+    "instrument_client",
+    "instrument_http_client",
+    "detect_llm_call",
+    "trigger_test_call",
+    "count_tokens",
+    "llm_span_with_tokens",
+    "llm_streaming_span",
+    "wrap_stream",
+    "wrap_async_stream",
+    "scan_prompt",
+    "init_metrics_pipeline",
+    "record_span_metrics",
+    "should_sample",
+]

instrumentation_sdk-1.7.0/src/api/rest/v1/app.py

@@ -0,0 +1,16 @@
+from fastapi import FastAPI
+import os
+
+from .router import api_v1_router
+from ....infra.tracing.middleware import instrument_app
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="Instrumentation SDK API", version="1.0.0")
+    app.include_router(api_v1_router, prefix="/v1")
+    instrument_app(app)
+    return app
+
+# Always define the app instance for ASGI servers like uvicorn
+app = create_app()
+
+# Build cache test

instrumentation_sdk-1.7.0/src/api/rest/v1/handlers/deterministic_sampling.py

@@ -0,0 +1,30 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+import os
+from opentelemetry import trace
+from .....features.deterministic_sampling.index import should_sample
+
+router = APIRouter(prefix="/sampling", tags=["Deterministic Sampling"])
+
+class SamplingGateRequest(BaseModel):
+    span_id: str
+
+class SamplingGateResponse(BaseModel):
+    is_sampled: bool
+
+def _set_span_attributes() -> None:
+    span = trace.get_current_span()
+    span.set_attribute("service.name", "instrumentation-sdk-api")
+    span.set_attribute("deployment.env", os.getenv("DEPLOYMENT_ENV", "dev"))
+    span.set_attribute("feature.name", "deterministic_sampling")
+
+@router.post("/should-sample", response_model=SamplingGateResponse)
+def should_sample_endpoint(request: SamplingGateRequest) -> SamplingGateResponse:
+    _set_span_attributes()
+    try:
+        sampled = should_sample(request.span_id)
+        span = trace.get_current_span()
+        span.set_attribute("llm.is_sampled", sampled)
+        return SamplingGateResponse(is_sampled=sampled)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

instrumentation_sdk-1.7.0/src/api/rest/v1/handlers/instrumentation.py

@@ -0,0 +1,73 @@
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+from pydantic import BaseModel
+from typing import Optional, Dict, Any
+import os
+from opentelemetry import trace
+from .....features.auto_instrumentation import (
+    init_auto_instrumentation,
+    uninstrument_all,
+    detect_llm_call,
+    trigger_test_call
+)
+
+
+router = APIRouter(prefix="/instrumentation", tags=["Instrumentation"])
+
+class StatusResponse(BaseModel):
+    success: bool
+    message: str
+
+class DetectionRequest(BaseModel):
+    url: str
+    body: str
+
+class DetectionResponse(BaseModel):
+    provider: str
+    model: str
+
+class TestCallRequest(BaseModel):
+    method: str
+    provider: str
+
+def _set_span_attributes():
+    span = trace.get_current_span()
+    span.set_attribute("service.name", "instrumentation-sdk-api")
+    span.set_attribute("deployment.env", os.getenv("DEPLOYMENT_ENV", "dev"))
+    span.set_attribute("feature.name", "auto_instrumentation")
+
+
+@router.post("/init", response_model=StatusResponse)
+def init_instrumentation():
+    _set_span_attributes()
+    try:
+        init_auto_instrumentation()
+        return StatusResponse(success=True, message="Auto-instrumentation initialized")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/uninstrument", response_model=StatusResponse)
+def uninstrument():
+    _set_span_attributes()
+    try:
+        uninstrument_all()
+        return StatusResponse(success=True, message="All instrumentation disabled")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/detect", response_model=DetectionResponse)
+def detect(request: DetectionRequest):
+    _set_span_attributes()
+    result = detect_llm_call(request.url, request.body)
+    return DetectionResponse(**result)
+
+
+
+
+@router.post("/test-call", response_model=StatusResponse)
+async def test_call(request: TestCallRequest):
+    _set_span_attributes()
+    result = await trigger_test_call(request.method, request.provider)
+    if not result["success"]:
+        raise HTTPException(status_code=500, detail=result["message"])
+    return StatusResponse(**result)
+

instrumentation_sdk-1.7.0/src/api/rest/v1/handlers/metrics.py

@@ -0,0 +1,104 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from typing import Optional, Dict, Any, List
+import os
+from opentelemetry import trace
+from .....features.metrics.index import record_span_metrics, init_metrics_pipeline
+
+
+router = APIRouter(prefix="/metrics", tags=["Metrics"])
+
+
+class MetricsStatusResponse(BaseModel):
+    initialized: bool
+    message: str
+
+
+class MetricsInitRequest(BaseModel):
+    port: Optional[int] = None
+
+
+class RecordSpanMetricsRequest(BaseModel):
+    model: str = "unknown"
+    provider: str = "unknown"
+    service_name: str = "unknown"
+    prompt_tokens: Optional[int] = None
+    completion_tokens: Optional[int] = None
+    cost_usd_micro: Optional[int] = None
+    latency_ms_total: Optional[int] = None
+    latency_ms_ttft: Optional[int] = None
+    finish_reason: Optional[str] = None
+    status: str = "success"
+    pii_detected: bool = False
+    injection_attempt: bool = False
+    retry_count: int = 0
+
+
+class RecordSpanMetricsResponse(BaseModel):
+    recorded: bool
+    cost_usd_micro: Optional[int] = None
+    price_version: Optional[str] = None
+
+
+class BatchRecordRequest(BaseModel):
+    spans: List[RecordSpanMetricsRequest]
+
+
+class BatchRecordResponse(BaseModel):
+    recorded_count: int
+
+
+def _set_span_attributes() -> None:
+    span = trace.get_current_span()
+    span.set_attribute("service.name", "instrumentation-sdk-api")
+    span.set_attribute("deployment.env", os.getenv("DEPLOYMENT_ENV", "dev"))
+    span.set_attribute("feature.name", "metrics")
+
+
+@router.post("/init", response_model=MetricsStatusResponse)
+def init_metrics(request: MetricsInitRequest = MetricsInitRequest()):
+    _set_span_attributes()
+    try:
+        init_metrics_pipeline(request.port)
+        return MetricsStatusResponse(initialized=True, message="Metrics pipeline initialized")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/health", response_model=MetricsStatusResponse)
+def metrics_health():
+    _set_span_attributes()
+    from .....features.metrics.index import _initialized
+    return MetricsStatusResponse(
+        initialized=_initialized,
+        message="Metrics pipeline is active" if _initialized else "Metrics pipeline not initialized"
+    )
+
+
+@router.post("/record", response_model=RecordSpanMetricsResponse)
+def record_metrics(request: RecordSpanMetricsRequest):
+    _set_span_attributes()
+    try:
+        span_data = request.model_dump(exclude_none=True)
+        record_span_metrics(span_data)
+        return RecordSpanMetricsResponse(
+            recorded=True,
+            cost_usd_micro=span_data.get("cost_usd_micro"),
+            price_version=span_data.get("price_version"),
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/record-batch", response_model=BatchRecordResponse)
+def record_batch(request: BatchRecordRequest):
+    _set_span_attributes()
+    count = 0
+    for span_req in request.spans:
+        try:
+            span_data = span_req.model_dump(exclude_none=True)
+            record_span_metrics(span_data)
+            count += 1
+        except Exception:
+            pass
+    return BatchRecordResponse(recorded_count=count)

instrumentation_sdk-1.7.0/src/api/rest/v1/handlers/minilm_embedding.py

@@ -0,0 +1,32 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+import os
+from opentelemetry import trace
+from .....features.minilm_embedding.index import get_embedding
+
+router = APIRouter(prefix="/embeddings", tags=["MiniLM Embedding"])
+
+class EmbeddingRequest(BaseModel):
+    text: str
+
+class EmbeddingResponse(BaseModel):
+    embedding: list[float]
+
+def _set_span_attributes() -> None:
+    span = trace.get_current_span()
+    span.set_attribute("service.name", "instrumentation-sdk-api")
+    span.set_attribute("deployment.env", os.getenv("DEPLOYMENT_ENV", "dev"))
+    span.set_attribute("feature.name", "minilm_embedding")
+
+@router.post("/embed", response_model=EmbeddingResponse)
+async def embed_endpoint(request: EmbeddingRequest) -> EmbeddingResponse:
+    _set_span_attributes()
+    try:
+        emb = await get_embedding(request.text)
+        if emb is None:
+            raise HTTPException(status_code=500, detail="Failed to generate embedding")
+        return EmbeddingResponse(embedding=emb)
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

instrumentation_sdk-1.7.0/src/api/rest/v1/handlers/pii_injection.py

@@ -0,0 +1,33 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from typing import Union, List, Dict, Any
+import os
+from opentelemetry import trace
+from .....features.pii_injection_scan.index import scan_prompt
+
+router = APIRouter(prefix="/pii-injection", tags=["PII & Injection Scan"])
+
+class PiiInjectionScanRequest(BaseModel):
+    prompt: Union[str, List[Dict[str, Any]]]
+
+class PiiInjectionScanResponse(BaseModel):
+    pii_detected: bool
+    injection_attempt: bool
+
+def _set_span_attributes() -> None:
+    span = trace.get_current_span()
+    span.set_attribute("service.name", "instrumentation-sdk-api")
+    span.set_attribute("deployment.env", os.getenv("DEPLOYMENT_ENV", "dev"))
+    span.set_attribute("feature.name", "pii_injection_scan")
+
+@router.post("/scan", response_model=PiiInjectionScanResponse)
+def scan(request: PiiInjectionScanRequest) -> PiiInjectionScanResponse:
+    _set_span_attributes()
+    try:
+        pii, inj = scan_prompt(request.prompt)
+        span = trace.get_current_span()
+        span.set_attribute("llm.pii_detected", pii)
+        span.set_attribute("llm.injection_attempt", inj)
+        return PiiInjectionScanResponse(pii_detected=pii, injection_attempt=inj)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

instrumentation_sdk-1.7.0/src/api/rest/v1/handlers/streaming.py

@@ -0,0 +1,55 @@
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from typing import List, Optional
+import os
+import asyncio
+from opentelemetry import trace
+from .....features.streaming.index import llm_streaming_span, wrap_async_stream
+
+router = APIRouter(prefix="/streaming", tags=["Streaming"])
+
+class TestStreamRequest(BaseModel):
+    provider: str
+    chunks: Optional[List[str]] = None
+
+def _set_span_attributes():
+    span = trace.get_current_span()
+    span.set_attribute("service.name", "instrumentation-sdk-api")
+    span.set_attribute("deployment.env", os.getenv("DEPLOYMENT_ENV", "dev"))
+    span.set_attribute("feature.name", "streaming")
+
+async def mock_async_stream(chunks: List[str]):
+    for chunk in chunks:
+        await asyncio.sleep(0.01)
+        yield chunk
+
+@router.post("/test-stream-call")
+async def test_stream_call(request: TestStreamRequest):
+    _set_span_attributes()
+    try:
+        chunks = request.chunks
+        if not chunks:
+            chunks = ["Hello ", "there! ", "This ", "is ", "a ", "mock ", "stream."]
+        
+        span_ctx = llm_streaming_span(
+            span_type="llm_call",
+            provider=request.provider,
+            model="test-stream-model",
+            prompt="Triggered via API verification endpoint",
+        )
+        
+        wrapped_stream = wrap_async_stream(
+            mock_async_stream(chunks),
+            span_context=span_ctx,
+            model="test-stream-model"
+        )
+        
+        async def event_generator():
+            async with span_ctx:
+                async for chunk in wrapped_stream:
+                    yield f"data: {chunk}\n\n"
+                    
+        return StreamingResponse(event_generator(), media_type="text/event-stream")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

instrumentation_sdk-1.7.0/src/api/rest/v1/handlers/token_counting.py

@@ -0,0 +1,31 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from typing import Union, List, Dict, Any
+import os
+from opentelemetry import trace
+from .....features.token_counting.index import count_tokens
+
+router = APIRouter(prefix="/token-counting", tags=["Token Counting"])
+
+class TokenCountRequest(BaseModel):
+    prompt: Union[str, List[Dict[str, Any]]]
+    model: str
+
+class TokenCountResponse(BaseModel):
+    tokens: int
+    method: str
+
+def _set_span_attributes():
+    span = trace.get_current_span()
+    span.set_attribute("service.name", "instrumentation-sdk-api")
+    span.set_attribute("deployment.env", os.getenv("DEPLOYMENT_ENV", "dev"))
+    span.set_attribute("feature.name", "token_counting")
+
+@router.post("/count", response_model=TokenCountResponse)
+def count(request: TokenCountRequest):
+    _set_span_attributes()
+    try:
+        tokens, method = count_tokens(request.prompt, request.model)
+        return TokenCountResponse(tokens=tokens, method=method)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

instrumentation_sdk-1.7.0/src/api/rest/v1/router.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter
+from .handlers.instrumentation import router as instrumentation_router
+from .handlers.token_counting import router as token_counting_router
+from .handlers.streaming import router as streaming_router
+from .handlers.pii_injection import router as pii_injection_router
+from .handlers.metrics import router as metrics_router
+from .handlers.deterministic_sampling import router as deterministic_sampling_router
+from .handlers.minilm_embedding import router as minilm_embedding_router
+
+api_v1_router = APIRouter()
+api_v1_router.include_router(instrumentation_router)
+api_v1_router.include_router(token_counting_router)
+api_v1_router.include_router(streaming_router)
+api_v1_router.include_router(pii_injection_router)
+api_v1_router.include_router(metrics_router)
+api_v1_router.include_router(deterministic_sampling_router)
+api_v1_router.include_router(minilm_embedding_router)
+

instrumentation_sdk-1.7.0/src/features/auto_instrumentation/__init__.py

@@ -0,0 +1,18 @@
+from .index import (
+    init_auto_instrumentation, 
+    uninstrument_all, 
+    instrument_client,
+    instrument_http_client,
+    detect_llm_call,
+    trigger_test_call
+)
+
+__all__ = [
+    "init_auto_instrumentation", 
+    "uninstrument_all", 
+    "instrument_client",
+    "instrument_http_client",
+    "detect_llm_call",
+    "trigger_test_call"
+]
+

instrumentation_sdk-1.7.0/src/features/auto_instrumentation/domain/mappers.py

@@ -0,0 +1,71 @@
+from typing import Any, Dict, Optional
+from ...spans.types import FinishReason
+
+class ProviderMapper:
+    @staticmethod
+    def map_openai_response(response: Any) -> Dict[str, Any]:
+        usage = getattr(response, "usage", None)
+        choices = getattr(response, "choices", [])
+        
+        finish_reason = FinishReason.UNSPECIFIED
+        if choices:
+            reason = choices[0].finish_reason
+            if reason == "stop":
+                finish_reason = FinishReason.STOP
+            elif reason == "length":
+                finish_reason = FinishReason.LENGTH
+            elif reason == "content_filter":
+                finish_reason = FinishReason.CONTENT_FILTER
+            elif reason == "tool_calls":
+                finish_reason = FinishReason.TOOL_CALLS
+
+        return {
+            "model": response.model,
+            "provider": "openai",
+            "prompt_tokens": usage.prompt_tokens if usage else 1,
+            "completion_tokens": usage.completion_tokens if usage else 0,
+            "finish_reason": finish_reason,
+            "response_content": choices[0].message.content if choices and hasattr(choices[0].message, "content") else None
+        }
+
+    @staticmethod
+    def map_anthropic_response(response: Any) -> Dict[str, Any]:
+        usage = getattr(response, "usage", None)
+        
+        finish_reason = FinishReason.UNSPECIFIED
+        stop_reason = getattr(response, "stop_reason", None)
+        if stop_reason == "end_turn":
+            finish_reason = FinishReason.STOP
+        elif stop_reason == "max_tokens":
+            finish_reason = FinishReason.LENGTH
+        elif stop_reason == "stop_sequence":
+            finish_reason = FinishReason.STOP
+        elif stop_reason == "tool_use":
+            finish_reason = FinishReason.TOOL_CALLS
+
+        content = ""
+        if hasattr(response, "content") and response.content:
+            content = response.content[0].text if hasattr(response.content[0], "text") else ""
+
+        return {
+            "model": response.model,
+            "provider": "anthropic",
+            "prompt_tokens": usage.input_tokens if usage else 1,
+            "completion_tokens": usage.output_tokens if usage else 0,
+            "finish_reason": finish_reason,
+            "response_content": content
+        }
+    @staticmethod
+    def map_langchain_response(response: Any, model: str, provider: str) -> Dict[str, Any]:
+        usage = getattr(response, "usage_metadata", {})
+        if not usage:
+            usage = {}
+            
+        return {
+            "model": model,
+            "provider": f"langchain:{provider}",
+            "prompt_tokens": usage.get("input_tokens", 1),
+            "completion_tokens": usage.get("output_tokens", 0),
+            "finish_reason": FinishReason.STOP if hasattr(response, "content") else FinishReason.UNSPECIFIED,
+            "response_content": getattr(response, "content", "")
+        }

instrumentation_sdk-1.7.0/src/features/auto_instrumentation/index.py

@@ -0,0 +1,70 @@
+from .service import AutoInstrumentationService
+from .infra.patchers.openai_patcher import OpenAIPatcher
+from .infra.patchers.anthropic_patcher import AnthropicPatcher
+from .infra.patchers.litellm_patcher import LiteLLMPatcher
+from .infra.patchers.langchain_patcher import LangChainPatcher
+from .infra.patchers.http_patcher import HTTPPatcher
+
+from typing import Dict, Any, Optional
+
+_SERVICE = AutoInstrumentationService(
+    patchers=[
+        OpenAIPatcher(),
+        AnthropicPatcher(),
+        LiteLLMPatcher(),
+        LangChainPatcher(),
+        HTTPPatcher()
+    ]
+)
+
+def init_auto_instrumentation() -> None:
+    _SERVICE.instrument_all()
+
+def uninstrument_all() -> None:
+    _SERVICE.uninstrument_all()
+
+def instrument_client(client: Any, provider: str) -> None:
+    _SERVICE.instrument_client(client, provider)
+
+def instrument_http_client(client: Any, provider: Optional[str] = None) -> None:
+    for patcher in _SERVICE._patchers:
+        if isinstance(patcher, HTTPPatcher):
+            patcher.patch_instance(client)
+            return
+
+def detect_llm_call(url: str, body: str) -> Dict[str, str]:
+    for patcher in _SERVICE._patchers:
+        if isinstance(patcher, HTTPPatcher):
+            provider = patcher._detect_provider(url)
+            model = patcher._extract_model(body)
+            return {"provider": provider or "unknown", "model": model}
+    return {"provider": "unknown", "model": "unknown"}
+
+async def trigger_test_call(method: str, provider: str) -> Dict[str, Any]:
+    import httpx
+    import json
+    
+    url_map = {
+        "openai": "https://api.openai.com/v1/chat/completions",
+        "anthropic": "https://api.anthropic.com/v1/messages"
+    }
+    url = url_map.get(provider, "https://api.openai.com/v1/chat/completions")
+    payload = {"model": "instrumentation-test-model"}
+    
+    try:
+        if method == "httpx":
+            async with httpx.AsyncClient() as client:
+                try:
+                    await client.post(url, json=payload, timeout=1.0)
+                except httpx.HTTPError:
+                    pass
+        elif method == "requests":
+            import requests
+            try:
+                requests.post(url, json=payload, timeout=1.0)
+            except requests.RequestException:
+                pass
+        
+        return {"success": True, "message": f"Test call triggered via {method} for {provider}"}
+    except Exception as e:
+        return {"success": False, "message": str(e)}