lanternfish 0.3.0__py3-none-any.whl

lanternfish/instrument.py

@@ -0,0 +1,181 @@
+"""
+SDK giriş noktası.
+
+Görev: `instrument()` ile provider'ı kurar, global OpenTelemetry provider'ı yapar (elle açılan span'ler de gitsin diye),
+       göndericiyi bağlar ve yüklü LLM/framework kütüphanelerini enstrümante eder. HTTP, SQL ve Redis yalnız istenirse
+       açılır. `flush()` ve `shutdown()` bekleyen span'leri gönderir.
+Yapmaz: Span'i kendisi çevirmez veya göndermez (json_exporter.py); entegrasyon ayrıntısı içermez (integrations/).
+"""
+
+import logging
+import os
+from collections.abc import Callable, Iterable
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+
+from lanternfish.configuration import resolve_api_key, resolve_endpoint, resolve_environment, resolve_release
+from lanternfish.errors import LanternfishConfigurationError
+from lanternfish.exporters import configure_exporter
+from lanternfish.integrations import (
+    instrument_anthropic,
+    instrument_autogen,
+    instrument_crewai,
+    instrument_gemini,
+    instrument_groq,
+    instrument_haystack,
+    instrument_http,
+    instrument_langchain,
+    instrument_llamaindex,
+    instrument_mcp,
+    instrument_mcp_server,
+    instrument_ollama,
+    instrument_openai,
+    instrument_openai_agents,
+    instrument_pydantic_ai,
+    instrument_redis,
+    instrument_sql,
+)
+from lanternfish.providers import create_tracer_provider
+from lanternfish.span_processor import AGENT_NAME_KEY, ENVIRONMENT_KEY, RELEASE_KEY
+
+logger = logging.getLogger("lanternfish")
+
+Integration = Callable[[TracerProvider], None]
+
+# Yüklü olan her zaman açılır: agent'ın LLM ve framework çağrıları.
+_INTEGRATIONS: list[tuple[str, Integration]] = [
+    ("openai", instrument_openai),  # Azure OpenAI istemcisi de aynı paketten izlenir.
+    ("anthropic", instrument_anthropic),
+    ("gemini", instrument_gemini),
+    ("groq", instrument_groq),
+    ("ollama", instrument_ollama),
+    ("langchain", instrument_langchain),
+    ("crewai", instrument_crewai),
+    ("llamaindex", instrument_llamaindex),
+    ("haystack", instrument_haystack),
+    ("openai_agents", instrument_openai_agents),
+    ("pydantic_ai", instrument_pydantic_ai),
+    ("autogen", instrument_autogen),
+    ("mcp", instrument_mcp),
+    ("mcp_server", instrument_mcp_server),
+]
+# Yalnız `include=` ile açılır: agent dışındaki her sorgu ve istek de kayıt olur, kotayı ve gürültüyü artırır.
+OPTIONAL_INTEGRATIONS: dict[str, Integration] = {
+    "http": instrument_http,
+    "sql": instrument_sql,
+    "redis": instrument_redis,
+}
+
+CONTENT_SWITCH_ENV = "TRACELOOP_TRACE_CONTENT"
+
+_provider: TracerProvider | None = None
+_owns_provider = False
+
+
+def instrument(
+    api_key: str | None = None,
+    endpoint: str | None = None,
+    *,
+    agent: str | None = None,
+    release: str | None = None,
+    environment: str | None = None,
+    include: Iterable[str] = (),
+    capture_content: bool = True,
+) -> None:
+    """Lanternfish izlemesini başlatır. Uygulama açılışında bir kez çağrılır; ikinci çağrı etkisizdir.
+
+    Args:
+        api_key: Proje API anahtarı; verilmezse LANTERNFISH_API_KEY.
+        endpoint: Backend adresi; verilmezse LANTERNFISH_ENDPOINT. Varsayılan adres yoktur.
+        agent: Her run'a yazılacak agent adı (ör. "travel-agent").
+        release: Çalışan sürüm; verilmezse LANTERNFISH_RELEASE ya da CI'ın commit değişkeni (GITHUB_SHA vb.).
+        environment: Ortam adı (ör. "production"); verilmezse LANTERNFISH_ENVIRONMENT.
+        include: Ek olarak açılacak entegrasyonlar: "http", "sql", "redis".
+        capture_content: LLM entegrasyonları prompt ve yanıt metnini kaydetsin mi. Kişisel veri işleyen agent'larda
+            False verin; model, token ve süre yine kaydedilir.
+
+    Raises:
+        LanternfishConfigurationError: Anahtar veya adres eksik/geçersizse ya da `include` tanınmayan ad içeriyorsa.
+    """
+    global _provider, _owns_provider
+    if _provider is not None:
+        logger.warning("Lanternfish: instrument() was already called; the second call is ignored.")
+        return
+
+    resolved_endpoint = resolve_endpoint(endpoint)
+    resolved_key = resolve_api_key(api_key)
+    optional = _optional_integrations(include)
+
+    # Uygulama kendi OpenTelemetry provider'ını kurduysa (Logfire, kendi OTel kurulumu) ona eklenir; ikinci bir global
+    # provider kurulamaz ve elle açılan span'ler onunkine giderdi.
+    existing = trace.get_tracer_provider()
+    owns_provider = not isinstance(existing, TracerProvider)
+    provider = create_tracer_provider() if owns_provider else existing
+    configure_exporter(
+        provider,
+        resolved_key,
+        resolved_endpoint,
+        {
+            AGENT_NAME_KEY: agent or "",
+            RELEASE_KEY: resolve_release(release) or "",
+            ENVIRONMENT_KEY: resolve_environment(environment) or "",
+        },
+    )
+    if owns_provider:
+        trace.set_tracer_provider(provider)
+    _provider, _owns_provider = provider, owns_provider
+
+    # Hazır LLM instrumentor'ları (OpenLLMetry) metni bu değişkene göre kaydeder; her çağrıda okurlar.
+    os.environ[CONTENT_SWITCH_ENV] = "true" if capture_content else "false"
+    enabled = [name for name, integration in [*_INTEGRATIONS, *optional] if _enable(name, integration, provider)]
+    logger.info("Lanternfish: tracing to %s (%s)", resolved_endpoint, ", ".join(enabled) or "manual spans only")
+
+
+def flush(timeout_seconds: float = 10.0) -> bool:
+    """Bekleyen span'leri hemen gönderir. Serverless işlevlerin ve kısa betiklerin sonunda çağırın.
+
+    Returns:
+        Süre dolmadan gönderildiyse True; instrument() çağrılmadıysa da True.
+    """
+    if _provider is None:
+        return True
+    return _provider.force_flush(int(timeout_seconds * 1000))
+
+
+def shutdown() -> None:
+    """Bekleyen span'leri gönderir ve izlemeyi kapatır. Süreç kapanırken kendiliğinden de çalışır.
+
+    Provider uygulamanınsa yalnız bekleyenler gönderilir; uygulamanın provider'ı kapatılmaz.
+    """
+    global _provider
+    if _provider is None:
+        return
+    if _owns_provider:
+        _provider.shutdown()
+    else:
+        _provider.force_flush()
+    _provider = None
+
+
+def _optional_integrations(include: Iterable[str]) -> list[tuple[str, Integration]]:
+    """`include` adlarını entegrasyonlara çevirir; tanınmayan adı hemen bildirir."""
+    names = list(dict.fromkeys(name.strip().lower() for name in include))
+    unknown = [name for name in names if name not in OPTIONAL_INTEGRATIONS]
+    if unknown:
+        allowed = ", ".join(sorted(OPTIONAL_INTEGRATIONS))
+        raise LanternfishConfigurationError(f"Unknown include= value(s): {', '.join(unknown)}. Use: {allowed}.")
+    return [(name, OPTIONAL_INTEGRATIONS[name]) for name in names]
+
+
+def _enable(name: str, integration: Integration, provider: TracerProvider) -> bool:
+    """Bir entegrasyonu açar; kütüphane yüklü değilse veya uyumsuzsa sessizce atlar."""
+    try:
+        integration(provider)
+    except ModuleNotFoundError:
+        logger.debug("Lanternfish: %s skipped (package not installed)", name)
+        return False
+    except Exception as error:  # noqa: BLE001  Bir entegrasyonun hatası agent'ı durdurmamalı.
+        logger.warning("Lanternfish: %s instrumentation was skipped (%s: %s)", name, type(error).__name__, error)
+        return False
+    return True

lanternfish/integrations/__init__.py

@@ -0,0 +1,61 @@
+"""
+Entegrasyon kayıt defteri.
+
+Görev: Her entegrasyonu ilk çağrıldığında içe aktaran ince sarmalayıcıları dışa verir. İlgili kütüphane yüklü değilse
+       ImportError çağırana (instrument()) çıkar; instrument() o entegrasyonu "atlandı" sayar.
+Yapmaz: Enstrümantasyon mantığı içermez (her biri kendi modülünde).
+"""
+
+from collections.abc import Callable
+from importlib import import_module
+
+from opentelemetry.sdk.trace import TracerProvider
+
+
+def _lazy(module: str, function: str) -> Callable[[TracerProvider], None]:
+    """Modülü ancak entegrasyon açılırken içe aktaran sarmalayıcı döndürür."""
+
+    def enable(tracer_provider: TracerProvider) -> None:
+        getattr(import_module(f"lanternfish.integrations.{module}"), function)(tracer_provider)
+
+    enable.__name__ = function
+    return enable
+
+
+instrument_openai = _lazy("openai", "instrument_openai")
+instrument_anthropic = _lazy("anthropic", "instrument_anthropic")
+instrument_gemini = _lazy("gemini", "instrument_gemini")
+instrument_groq = _lazy("groq", "instrument_groq")
+instrument_ollama = _lazy("ollama", "instrument_ollama")
+instrument_langchain = _lazy("langchain", "instrument_langchain")
+instrument_crewai = _lazy("crewai", "instrument_crewai")
+instrument_llamaindex = _lazy("llamaindex", "instrument_llamaindex")
+instrument_haystack = _lazy("haystack", "instrument_haystack")
+instrument_openai_agents = _lazy("openai_agents", "instrument_openai_agents")
+instrument_pydantic_ai = _lazy("pydantic_ai", "instrument_pydantic_ai")
+instrument_autogen = _lazy("autogen", "instrument_autogen")
+instrument_mcp = _lazy("mcp", "instrument_mcp")
+instrument_mcp_server = _lazy("mcp", "instrument_mcp_server")
+instrument_http = _lazy("http", "instrument_http")
+instrument_sql = _lazy("sql", "instrument_sql")
+instrument_redis = _lazy("redis", "instrument_redis")
+
+__all__ = [
+    "instrument_anthropic",
+    "instrument_autogen",
+    "instrument_crewai",
+    "instrument_gemini",
+    "instrument_groq",
+    "instrument_haystack",
+    "instrument_http",
+    "instrument_langchain",
+    "instrument_llamaindex",
+    "instrument_mcp",
+    "instrument_mcp_server",
+    "instrument_ollama",
+    "instrument_openai",
+    "instrument_openai_agents",
+    "instrument_pydantic_ai",
+    "instrument_redis",
+    "instrument_sql",
+]

lanternfish/integrations/anthropic.py

@@ -0,0 +1,20 @@
+# anthropic.py
+# Görev: Anthropic Claude çağrılarını OpenTelemetry ile otomatik enstrümante etmek
+# Yapmaz: TracerProvider veya exporter oluşturmaz
+
+from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+
+from lanternfish.integrations.instrumentor import enable_instrumentor
+
+
+def instrument_anthropic(tracer_provider: TracerProvider) -> None:
+    """Anthropic SDK çağrılarını verilen tracer provider ile izler.
+
+    messages.create() çağrılarını yakalar; model adı, input/output token
+    sayıları, latency ve hata durumlarını gen_ai.* attribute'ları olarak kaydeder.
+
+    Args:
+        tracer_provider: Span'lerin gönderileceği TracerProvider.
+    """
+    enable_instrumentor(AnthropicInstrumentor(), tracer_provider)

lanternfish/integrations/autogen.py

@@ -0,0 +1,75 @@
+# autogen.py
+# Gorev: AutoGen 0.7+ (autogen-agentchat) agent/team run() cagrilarini OpenTelemetry ile enstrumante etmek
+# Yapmaz: TracerProvider veya exporter olusturmaz
+#
+# Gercek API (autogen-agentchat >= 0.6):
+#   AssistantAgent.run(task, cancellation_token=None, ...)  <- async
+#   RoundRobinGroupChat.run(task, ...)                      <- async (ayni imza)
+#   TaskResult.messages -> list[BaseAgentEvent | BaseChatMessage]
+#   TaskResult.stop_reason -> str | None
+
+import functools
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+
+
+def instrument_autogen(tracer_provider: TracerProvider) -> None:
+    """AutoGen AssistantAgent ve RoundRobinGroupChat run() cagrilarini izler.
+
+    Agent adi, model adi, mesaj sayisi ve stop_reason gen_ai.* + agent.*
+    attribute'lari olarak kaydedilir.
+
+    Args:
+        tracer_provider: Span'lerin gonderilecegi TracerProvider.
+    """
+    # Kütüphane yüklü değilse ImportError instrument()'a çıkar; o entegrasyon atlanır.
+    from autogen_agentchat.agents import AssistantAgent
+    from autogen_agentchat.teams import RoundRobinGroupChat
+
+    tracer = trace.get_tracer("lanternfish.autogen", tracer_provider=tracer_provider)
+
+    def _make_traced_run(original_run: Any, span_name: str) -> Any:
+        @functools.wraps(original_run)
+        async def traced_run(self: Any, *, task: Any = None, **kwargs: Any) -> Any:
+            agent_name = getattr(self, "name", type(self).__name__)
+
+            # Model bilgisini cek (AssistantAgent'ta _model_client var)
+            model_client = getattr(self, "_model_client", None)
+            model_name: str = "unknown"
+            if model_client is not None:
+                # OpenAIChatCompletionClient: _resolved_model (str) veya model / _model_name
+                model_name = (
+                    getattr(model_client, "_resolved_model", None)
+                    or getattr(model_client, "model", None)
+                    or getattr(model_client, "_model_name", None)
+                    or getattr(model_client, "_model", None)
+                    or type(model_client).__name__
+                )
+
+            with tracer.start_as_current_span(span_name) as span:
+                span.set_attribute("gen_ai.system", "autogen")
+                span.set_attribute("agent.name", str(agent_name))
+                span.set_attribute("gen_ai.request.model", str(model_name))
+
+                if task is not None:
+                    span.set_attribute("agent.task_preview", str(task)[:120])
+
+                # task keyword-only: positional olarak gecirilemez
+                result = await original_run(self, task=task, **kwargs)
+
+                messages = getattr(result, "messages", None)
+                if messages is not None:
+                    span.set_attribute("agent.message_count", len(messages))
+
+                stop_reason = getattr(result, "stop_reason", None)
+                if stop_reason is not None:
+                    span.set_attribute("agent.stop_reason", str(stop_reason))
+
+                return result
+
+        return traced_run
+
+    AssistantAgent.run = _make_traced_run(AssistantAgent.run, "autogen.agent.run")
+    RoundRobinGroupChat.run = _make_traced_run(RoundRobinGroupChat.run, "autogen.team.run")

lanternfish/integrations/crewai.py

@@ -0,0 +1,17 @@
+# crewai.py
+# Görev: CrewAI çağrılarını OpenTelemetry ile otomatik enstrümante etmek
+# Yapmaz: TracerProvider veya exporter oluşturmaz
+
+from opentelemetry.instrumentation.crewai import CrewAIInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+
+from lanternfish.integrations.instrumentor import enable_instrumentor
+
+
+def instrument_crewai(tracer_provider: TracerProvider) -> None:
+    """CrewAI agent/task/crew çağrılarını verilen tracer provider ile izler.
+
+    Args:
+        tracer_provider: Span'lerin gönderileceği TracerProvider.
+    """
+    enable_instrumentor(CrewAIInstrumentor(), tracer_provider)

lanternfish/integrations/gemini.py

@@ -0,0 +1,24 @@
+# gemini.py
+# Gorev: Google Gemini (google-genai SDK) cagrilarini OpenTelemetry ile otomatik enstrumante etmek
+# Yapmaz: TracerProvider veya exporter olusturmaz
+#
+# Not: Bu dosya google-genai SDK'yi izler (google.genai), eski google-generativeai
+# paketini degil. Dogru SDK: pip install google-genai
+
+from opentelemetry.instrumentation.google_generativeai import GoogleGenerativeAiInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+
+from lanternfish.integrations.instrumentor import enable_instrumentor
+
+
+def instrument_gemini(tracer_provider: TracerProvider) -> None:
+    """Google Gemini SDK cagrilarini verilen tracer provider ile izler.
+
+    google.genai.Client uzerindeki generate_content() cagrilarini yakalar;
+    model adi, token sayilari, latency ve hata durumlarini gen_ai.* attribute'lari
+    olarak kaydeder.
+
+    Args:
+        tracer_provider: Span'lerin gonderilecegi TracerProvider.
+    """
+    enable_instrumentor(GoogleGenerativeAiInstrumentor(), tracer_provider)

lanternfish/integrations/groq.py

@@ -0,0 +1,21 @@
+# groq.py
+# Gorev: Groq hizli inference cagrilarini OpenTelemetry ile otomatik enstrumante etmek
+# Yapmaz: TracerProvider veya exporter olusturmaz
+
+from opentelemetry.instrumentation.groq import GroqInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+
+from lanternfish.integrations.instrumentor import enable_instrumentor
+
+
+def instrument_groq(tracer_provider: TracerProvider) -> None:
+    """Groq SDK cagrilarini verilen tracer provider ile izler.
+
+    groq.Groq().chat.completions.create() cagrilarini yakalar; model adi,
+    token sayilari ve latency gen_ai.* attribute'lari olarak kaydedilir.
+    Groq'un cok dusuk latency'si (<100ms) span'lerde gorulur.
+
+    Args:
+        tracer_provider: Span'lerin gonderilecegi TracerProvider.
+    """
+    enable_instrumentor(GroqInstrumentor(), tracer_provider)

lanternfish/integrations/haystack.py

@@ -0,0 +1,65 @@
+# haystack.py
+# Gorev: Haystack 2.x (haystack-ai) pipeline cagrilarini OpenTelemetry ile enstrumante etmek
+# Yapmaz: TracerProvider veya exporter olusturmaz
+#
+# Haystack 2.x gercek API:
+#   Pipeline.run(data: dict, include_outputs_from=None, ...)  <- sync
+#   Pipeline.graph  <- networkx.MultiDiGraph, nodes listesi buradan alinir
+#   Sonuc: dict { component_name: { output_key: value } }
+
+import functools
+import os
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+
+
+def instrument_haystack(tracer_provider: TracerProvider) -> None:
+    """Haystack 2.x Pipeline.run() cagrilarini verilen tracer provider ile izler.
+
+    Pipeline.run() sararak; component sayisi, input verisi (ozet) ve
+    cikti anahtarlari haystack.* attribute'lari olarak kaydedilir.
+
+    Args:
+        tracer_provider: Span'lerin gonderilecegi TracerProvider.
+    """
+    # Haystack, global provider görünce kendi izlemesini açar ve açılışta deneme span'i gönderir; pipeline'ı
+    # burada izlediğimiz için onunki kapatılır (aksi hâlde her açılışta anlamsız bir run oluşur).
+    os.environ.setdefault("HAYSTACK_AUTO_TRACE_ENABLED", "false")
+    # Kütüphane yüklü değilse ImportError instrument()'a çıkar; o entegrasyon atlanır.
+    from haystack import Pipeline
+
+    tracer = trace.get_tracer("lanternfish.haystack", tracer_provider=tracer_provider)
+    original_run = Pipeline.run
+
+    @functools.wraps(original_run)
+    def traced_run(self: Any, data: Any = None, **kwargs: Any) -> Any:
+        with tracer.start_as_current_span("haystack.pipeline.run") as span:
+            span.set_attribute("gen_ai.system", "haystack")
+
+            # Haystack 2.x: graph is a networkx.MultiDiGraph
+            graph = getattr(self, "graph", None)
+            if graph is not None:
+                nodes = list(graph.nodes)
+                span.set_attribute("haystack.component_count", len(nodes))
+                span.set_attribute("haystack.components", str(nodes[:10]))
+
+            # data dict icinden query bul (orn: {"query": {"text": "..."}} veya {"text_file_converter": {...}})
+            if isinstance(data, dict):
+                span.set_attribute("haystack.input_components", str(list(data.keys())[:5]))
+                for val in data.values():
+                    if isinstance(val, dict):
+                        for k, v in val.items():
+                            if "query" in k.lower() or k == "query":
+                                span.set_attribute("haystack.query_preview", str(v)[:120])
+                                break
+
+            result = original_run(self, data, **kwargs)
+
+            if isinstance(result, dict):
+                span.set_attribute("haystack.output_components", str(list(result.keys())[:5]))
+
+            return result
+
+    Pipeline.run = traced_run

lanternfish/integrations/http.py

@@ -0,0 +1,129 @@
+"""
+HTTP istemci entegrasyonu (yalnız `include=["http"]` ile açılır).
+
+Görev: requests, httpx (sync/async) ve aiohttp isteklerini span olarak kaydeder: yöntem, host, yol, durum kodu, süre
+       ve hata türü. Lanternfish'in kendi gönderimlerini kaydetmez.
+Yapmaz: İstek/yanıt gövdesini, başlıkları veya sorgu parametrelerini kaydetmez (parola, token, kişisel veri taşıyabilir);
+        yanıtı okumaz (akış hâlindeki yanıtı bozmamak için).
+"""
+
+import functools
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+from urllib.parse import urlsplit
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.trace import Span, StatusCode, Tracer
+
+# Lanternfish'in kendi API yolları: bunları izlemek sonsuz döngü ve gürültü olurdu.
+_OWN_PATHS = ("/v1/traces", "/v1/deployments")
+
+
+def instrument_http(tracer_provider: TracerProvider) -> None:
+    """Yüklü HTTP kütüphanelerinin merkezi istek yöntemini sarar.
+
+    Args:
+        tracer_provider: Span'lerin gönderileceği provider.
+    """
+    tracer = otel_trace.get_tracer("lanternfish.http", tracer_provider=tracer_provider)
+    _instrument_requests(tracer)
+    _instrument_httpx(tracer)
+    _instrument_aiohttp(tracer)
+
+
+@contextmanager
+def _request_span(tracer: Tracer, system: str, method: str, url: str) -> Iterator[Span | None]:
+    """İstek için span açar; Lanternfish'in kendi isteğiyse span açmadan geçer."""
+    parts = urlsplit(url)
+    if parts.path.startswith(_OWN_PATHS):
+        yield None
+        return
+    host = parts.netloc or "unknown"
+    with tracer.start_as_current_span(f"http {method.upper()} {host}", record_exception=False,
+                                          set_status_on_exception=False) as span:
+        span.set_attribute("http.system", system)
+        span.set_attribute("http.method", method.upper())
+        span.set_attribute("http.host", host)
+        span.set_attribute("http.path", parts.path or "/")
+        try:
+            yield span
+        except Exception as error:
+            span.set_status(StatusCode.ERROR, type(error).__name__)
+            span.set_attribute("http.error.type", type(error).__name__)
+            raise
+
+
+def _record_status(span: Span | None, status_code: int) -> None:
+    """Durum kodunu yazar; 4xx/5xx yanıtı hata sayar."""
+    if span is None:
+        return
+    span.set_attribute("http.status_code", status_code)
+    if status_code >= 400:
+        span.set_status(StatusCode.ERROR, f"HTTP {status_code}")
+    else:
+        span.set_status(StatusCode.OK)
+
+
+def _instrument_requests(tracer: Tracer) -> None:
+    """requests.Session.request() sarmalayıcısı."""
+    try:
+        import requests
+    except ImportError:
+        return
+    original = requests.Session.request
+
+    @functools.wraps(original)
+    def traced(self: Any, method: str, url: str, *args: Any, **kwargs: Any) -> Any:
+        with _request_span(tracer, "requests", method, str(url)) as span:
+            response = original(self, method, url, *args, **kwargs)
+            _record_status(span, response.status_code)
+            return response
+
+    requests.Session.request = traced
+
+
+def _instrument_httpx(tracer: Tracer) -> None:
+    """httpx.Client.send() ve httpx.AsyncClient.send() sarmalayıcıları."""
+    try:
+        import httpx
+    except ImportError:
+        return
+    original_sync = httpx.Client.send
+    original_async = httpx.AsyncClient.send
+
+    @functools.wraps(original_sync)
+    def traced_sync(self: Any, request: Any, **kwargs: Any) -> Any:
+        with _request_span(tracer, "httpx", request.method, str(request.url)) as span:
+            response = original_sync(self, request, **kwargs)
+            _record_status(span, response.status_code)
+            return response
+
+    @functools.wraps(original_async)
+    async def traced_async(self: Any, request: Any, **kwargs: Any) -> Any:
+        with _request_span(tracer, "httpx", request.method, str(request.url)) as span:
+            response = await original_async(self, request, **kwargs)
+            _record_status(span, response.status_code)
+            return response
+
+    httpx.Client.send = traced_sync
+    httpx.AsyncClient.send = traced_async
+
+
+def _instrument_aiohttp(tracer: Tracer) -> None:
+    """aiohttp.ClientSession._request() sarmalayıcısı."""
+    try:
+        import aiohttp
+    except ImportError:
+        return
+    original = aiohttp.ClientSession._request
+
+    @functools.wraps(original)
+    async def traced(self: Any, method: str, str_or_url: Any, **kwargs: Any) -> Any:
+        with _request_span(tracer, "aiohttp", method, str(str_or_url)) as span:
+            response = await original(self, method, str_or_url, **kwargs)
+            _record_status(span, response.status)
+            return response
+
+    aiohttp.ClientSession._request = traced

lanternfish/integrations/instrumentor.py

@@ -0,0 +1,24 @@
+"""
+Hazır OpenTelemetry instrumentor'larını açma yardımcısı.
+
+Görev: Bir instrumentor'ı yalnız hedef kütüphane yüklü ve sürümü uyumluyken açar; değilse ModuleNotFoundError
+       fırlatır, böylece instrument() onu "atlandı" sayar ve kullanıcının ekranına uyumsuzluk satırı düşmez.
+Yapmaz: Hangi instrumentor'ın açılacağına karar vermez (instrument.py).
+"""
+
+from opentelemetry.instrumentation.dependencies import get_dependency_conflicts
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+
+
+def enable_instrumentor(instrumentor: BaseInstrumentor, tracer_provider: TracerProvider) -> None:
+    """Instrumentor'ı bağımlılığı karşılanıyorsa ve henüz açık değilse verilen provider ile açar.
+
+    Raises:
+        ModuleNotFoundError: Hedef kütüphane yüklü değil veya sürümü desteklenmiyorsa.
+    """
+    conflict = get_dependency_conflicts(instrumentor.instrumentation_dependencies())
+    if conflict is not None:
+        raise ModuleNotFoundError(str(conflict))
+    if not instrumentor.is_instrumented_by_opentelemetry:
+        instrumentor.instrument(tracer_provider=tracer_provider)

lanternfish/integrations/langchain.py

@@ -0,0 +1,21 @@
+# langchain.py
+# Görev: LangChain çağrılarını OpenTelemetry ile otomatik enstrümante etmek
+# Yapmaz: TracerProvider veya exporter oluşturmaz
+
+from opentelemetry.instrumentation.langchain import LangchainInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+
+from lanternfish.integrations.instrumentor import enable_instrumentor
+
+
+def instrument_langchain(tracer_provider: TracerProvider) -> None:
+    """LangChain çağrılarını verilen tracer provider ile izler.
+
+    Tool call'lar dahil tüm LangChain callback olayları otomatik yakalanır;
+    tool span'leri OpenTelemetry GenAI konvansiyonuna göre
+    "execute_tool <tool_name>" adıyla oluşturulur (örn. "execute_tool multiply").
+
+    Args:
+        tracer_provider: Span'lerin gönderileceği TracerProvider.
+    """
+    enable_instrumentor(LangchainInstrumentor(), tracer_provider)

lanternfish/integrations/llamaindex.py

@@ -0,0 +1,21 @@
+# llamaindex.py
+# Gorev: LlamaIndex RAG cagrilarini OpenTelemetry ile otomatik enstrumante etmek
+# Yapmaz: TracerProvider veya exporter olusturmaz
+
+from opentelemetry.instrumentation.llamaindex import LlamaIndexInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+
+from lanternfish.integrations.instrumentor import enable_instrumentor
+
+
+def instrument_llamaindex(tracer_provider: TracerProvider) -> None:
+    """LlamaIndex RAG pipeline cagrilarini verilen tracer provider ile izler.
+
+    QueryEngine.query(), Retriever.retrieve() ve LLM cagrilarini otomatik
+    yakalar; node sayisi, token kullanimi ve latency gen_ai.* attribute'lari
+    olarak kaydedilir.
+
+    Args:
+        tracer_provider: Span'lerin gonderilecegi TracerProvider.
+    """
+    enable_instrumentor(LlamaIndexInstrumentor(), tracer_provider)