langgraph-api 0.11.0.dev10__tar.gz → 0.12.0.dev2__tar.gz

{langgraph_api-0.11.0.dev10 → langgraph_api-0.12.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.11.0.dev10
+Version: 0.12.0.dev2
 Author-email: Will Fu-Hinthorn <will@langchain.dev>, Josh Rogers <josh@langchain.dev>, Parker Rule <parker@langchain.dev>
 License: Elastic-2.0
 License-File: LICENSE
@@ -16,7 +16,7 @@ Requires-Dist: jsonschema-rs<0.45,>=0.20.0
 Requires-Dist: langchain-core>=0.3.64
 Requires-Dist: langchain-protocol<0.1,>=0.0.16
 Requires-Dist: langgraph-checkpoint<5,>=3.0.1
-Requires-Dist: langgraph-runtime-inmem<0.31.0.dev0,>=0.30.0.dev0
+Requires-Dist: langgraph-runtime-inmem<0.32.0.dev0,>=0.31.0.dev0
 Requires-Dist: langgraph-sdk>=0.3.5
 Requires-Dist: langgraph<2,>=0.4.10
 Requires-Dist: langsmith[otel]>=0.6.3

langgraph_api-0.12.0.dev2/langgraph_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.12.0.dev2"

langgraph_api-0.12.0.dev2/langgraph_api/api/meta.py

@@ -0,0 +1,122 @@
+import langgraph.version
+import structlog
+from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+from starlette.responses import JSONResponse, PlainTextResponse
+
+from langgraph_api import __version__, config, metadata
+from langgraph_api.feature_flags import IS_POSTGRES_OR_GRPC_BACKEND
+from langgraph_api.http_metrics import HTTP_METRICS_COLLECTOR
+from langgraph_api.route import ApiRequest
+from langgraph_api.schema import PoolStats, PostgresPoolStats, RedisPoolStats
+from langgraph_runtime.database import connect, pool_stats
+from langgraph_runtime.metrics import get_metrics
+
+if IS_POSTGRES_OR_GRPC_BACKEND:
+    from langgraph_api.grpc.ops import Runs
+else:
+    from langgraph_runtime.ops import Runs
+
+METRICS_FORMATS = {"prometheus", "json"}
+
+logger = structlog.stdlib.get_logger(__name__)
+
+
+def _merge_pool_stats(local: PoolStats, remote: PoolStats) -> PoolStats:
+    """Merge local and remote pool stats by summing numeric values. Used to aggregate Python + Go pool metrics."""
+    merged: PoolStats = {}
+    if "postgres" in local or "postgres" in remote:
+        lp = local.get("postgres") or {}
+        rp = remote.get("postgres") or {}
+        merged["postgres"] = PostgresPoolStats(
+            pool_max=lp.get("pool_max", 0) + rp.get("pool_max", 0),
+            pool_size=lp.get("pool_size", 0) + rp.get("pool_size", 0),
+            pool_available=lp.get("pool_available", 0) + rp.get("pool_available", 0),
+            requests_queued=lp.get("requests_queued", 0) + rp.get("requests_queued", 0),
+            requests_errors=lp.get("requests_errors", 0) + rp.get("requests_errors", 0),
+        )
+    if "redis" in local or "redis" in remote:
+        lr = local.get("redis") or {}
+        rr = remote.get("redis") or {}
+        merged["redis"] = RedisPoolStats(
+            idle_connections=lr.get("idle_connections", 0)
+            + rr.get("idle_connections", 0),
+            in_use_connections=lr.get("in_use_connections", 0)
+            + rr.get("in_use_connections", 0),
+            max_connections=lr.get("max_connections", 0) + rr.get("max_connections", 0),
+        )
+    return merged
+
+
+async def _grpc_pool_stats() -> PoolStats:
+    """Fetch connection pool stats from the Core API (Go) via gRPC for metrics aggregation. Returns {} on error."""
+    if not IS_POSTGRES_OR_GRPC_BACKEND:
+        return {}
+    try:
+        return await Runs.pool_stats()
+    except Exception as e:
+        await logger.awarning(
+            "Failed to fetch Core API pool stats for aggregation", exc_info=e
+        )
+        return {}
+
+
+async def meta_pool_stats() -> PoolStats:
+    local_pool_stats: PoolStats = pool_stats()
+
+    # Aggregate with Core API (Go) pool stats when using gRPC backend
+    grpc_pool_stats = await _grpc_pool_stats()
+    return _merge_pool_stats(local_pool_stats, grpc_pool_stats)
+
+
+async def meta_info(request: ApiRequest):
+    return JSONResponse(
+        {
+            "version": __version__,
+            "langgraph_py_version": langgraph.version.__version__,
+            "flags": {
+                "assistants": True,
+                "crons": True,
+                "langsmith": bool(config.LANGSMITH_CONTROL_PLANE_API_KEY)
+                and bool(config.TRACING),
+                "langsmith_tracing_replicas": True,
+            },
+            "host": {
+                "kind": metadata.HOST,
+                "project_id": metadata.PROJECT_ID,
+                "host_revision_id": metadata.HOST_REVISION_ID,
+                "revision_id": metadata.REVISION,
+                "tenant_id": metadata.TENANT_ID,
+            },
+        }
+    )
+
+
+async def meta_metrics(request: ApiRequest):
+    # determine output format
+    metrics_format = request.query_params.get("format", "prometheus")
+    if metrics_format not in METRICS_FORMATS:
+        metrics_format = "prometheus"
+
+    if metrics_format == "prometheus":
+        # Served straight from the OTLP Prometheus client's registry (see
+        # metrics_otlp._LSDPrometheusReader).
+        return PlainTextResponse(generate_latest(), media_type=CONTENT_TYPE_LATEST)
+
+    # JSON: hand-built snapshot of workers, queue depth, HTTP, and pool stats.
+    worker_metrics = get_metrics()["workers"]
+    http_metrics = HTTP_METRICS_COLLECTOR.get_metrics(
+        metadata.PROJECT_ID,
+        metadata.HOST_REVISION_ID,
+        metrics_format,
+        metadata.DEPLOYMENT_TYPE,
+    )
+    merged_pool_stats = await meta_pool_stats()
+    async with connect() as conn:
+        resp = {
+            **merged_pool_stats,
+            "queue": await Runs.stats(conn),
+            **http_metrics,
+        }
+        if config.N_JOBS_PER_WORKER > 0:
+            resp["workers"] = worker_metrics
+        return JSONResponse(resp)

{langgraph_api-0.11.0.dev10 → langgraph_api-0.12.0.dev2}/langgraph_api/config/__init__.py

@@ -577,8 +577,13 @@ METRIC_MAX_EMITTING_TIER = env(
     "METRIC_MAX_EMITTING_TIER", cast=int, default=_METRIC_MAX_EMITTING_TIER_DEFAULT
 )
 DATADOG_METRICS_ENABLED = bool(LSD_DD_API_KEY)
-LSD_PROM_METRICS_ENABLED = env("LSD_PROM_METRICS_ENABLED", cast=bool, default=False)
-LSD_PROM_METRICS_PORT = env("LSD_PROM_METRICS_PORT", cast=int, default=9464)
+# When true, the Prometheus scrape (/metrics) exposes ALL metrics, not just the
+# lsd_web_metric (Deployment-UI) set. Record-time tier filtering
+# (METRIC_MAX_EMITTING_TIER) still applies, so internal metrics must be within the
+# max emitting tier to be recorded at all.
+EXPOSE_INTERNAL_METRICS_PROMETHEUS = env(
+    "EXPOSE_INTERNAL_METRICS_PROMETHEUS", cast=bool, default=False
+)
 LANGGRAPH_LOGS_ENDPOINT = env("LANGGRAPH_LOGS_ENDPOINT", cast=str, default=None)
 LANGGRAPH_LOGS_ENABLED = env("LANGGRAPH_LOGS_ENABLED", cast=bool, default=False)
 
@@ -635,6 +640,7 @@ __all__ = [
     "CRON_SCHEDULER_SLEEP_TIME",
     "DATABASE_URI",
     "DATADOG_METRICS_ENABLED",
+    "EXPOSE_INTERNAL_METRICS_PROMETHEUS",
     "FF_CRONS_ENABLED",
     "FF_LOG_DROPPED_EVENTS",
     "FF_LOG_QUERY_AND_PARAMS",
@@ -672,8 +678,6 @@ __all__ = [
     "LSD_GRPC_SERVER_ADDRESS",
     "LSD_GRPC_SERVER_MAX_RECV_MSG_BYTES",
     "LSD_GRPC_SERVER_MAX_SEND_MSG_BYTES",
-    "LSD_PROM_METRICS_ENABLED",
-    "LSD_PROM_METRICS_PORT",
     "MAX_STREAM_CHUNK_SIZE_BYTES",
     "METRIC_MAX_EMITTING_TIER",
     "METRIC_PREFIX",

langgraph_api-0.12.0.dev2/langgraph_api/metrics_collector.py

@@ -0,0 +1,184 @@
+"""Periodic collector that pushes snapshot/state metrics to the OTLP client.
+
+This background task samples the same sources every ``STATS_INTERVAL_SECS`` and records them via the reporter.
+
+The loop runs in **every** process (on postgres both the API server and the
+dedicated queue worker share the same lifespan; inmem is a single process). Each
+metric group self-gates so it lands on the right process:
+
+- **worker gauges** — recorded wherever workers run (``N_JOBS_PER_WORKER > 0``):
+  the queue worker, or a combined single-process deployment. A distributed API
+  process (``N_JOBS_PER_WORKER == 0``) has no workers and skips them.
+- **queue depth** (``num_pending_runs``/``num_running_runs``) — a single global
+  value from ``Runs.stats`` (a gRPC call to the Go core). Emitted by the **API
+  process only** (``not IS_QUEUE_ENTRYPOINT``) on the **postgres** runtime; inmem
+  skips the DB round-trip entirely.
+- **Postgres + Redis pool stats** — recorded on **both** processes (postgres
+  runtime only), each reporting its own pools via ``meta_pool_stats()``, which
+  merges the local Python pools with the Go-core pools. Redis stats in particular
+  come from the local Python pool — the Go core omits them unless it has a
+  non-cluster redis client — so a Go-core-only source would drop them. inmem has
+  no real Postgres/Redis pools, so nothing is reported.
+
+The two pool request counters are cumulative, so we push the delta since the
+previous sample (OTLP counters are additive).
+
+The loop also logs the same samples (``Worker stats``, ``Postgres pool stats``,
+``Redis pool stats``) — folding in what the legacy per-process ``stats_loop``
+functions used to log.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import structlog
+
+from langgraph_api import config
+from langgraph_api.api.meta import meta_pool_stats
+from langgraph_api.feature_flags import IS_POSTGRES_OR_GRPC_BACKEND
+from langgraph_api.metrics_otlp import (
+    COUNTER_PG_POOL_REQUESTS_ERRORS,
+    COUNTER_PG_POOL_REQUESTS_QUEUED,
+    GAUGE_NUM_PENDING_RUNS,
+    GAUGE_NUM_RUNNING_RUNS,
+    GAUGE_PG_POOL_AVAILABLE,
+    GAUGE_PG_POOL_MAX,
+    GAUGE_PG_POOL_SIZE,
+    GAUGE_REDIS_POOL_AVAILABLE,
+    GAUGE_REDIS_POOL_MAX,
+    GAUGE_REDIS_POOL_SIZE,
+    GAUGE_WORKERS_ACTIVE,
+    GAUGE_WORKERS_AVAILABLE,
+    GAUGE_WORKERS_MAX,
+    get_otlp_metrics_reporter,
+)
+from langgraph_runtime.database import connect
+from langgraph_runtime.metrics import get_metrics
+
+if IS_POSTGRES_OR_GRPC_BACKEND:
+    from langgraph_api.grpc.ops import Runs
+else:
+    from langgraph_runtime.ops import Runs
+
+logger = structlog.stdlib.get_logger(__name__)
+
+
+async def _collect_queue_and_workers(reporter) -> None:
+    """Worker gauges (where workers run) + queue depth (API process only).
+
+    Worker counts are local to the process running this loop and emitted wherever
+    workers run (``N_JOBS_PER_WORKER > 0``) — the queue worker or a combined
+    single-process deployment; a distributed API process (N_JOBS == 0) skips them.
+
+    Queue depth is a single global value (from the run table, via ``Runs.stats`` —
+    a gRPC call to the Go core) and is emitted by the **API process only**
+    (``not IS_QUEUE_ENTRYPOINT``) on **postgres**: inmem skips the DB round-trip,
+    and the dedicated queue worker leaves it to the API process so the global value
+    is not double-reported across the queue/API split.
+    """
+    if config.N_JOBS_PER_WORKER > 0:
+        workers = get_metrics()["workers"]
+        reporter.record_gauge(GAUGE_WORKERS_MAX, workers["max"])
+        reporter.record_gauge(GAUGE_WORKERS_ACTIVE, workers["active"])
+        reporter.record_gauge(GAUGE_WORKERS_AVAILABLE, workers["available"])
+        await logger.ainfo(
+            "Worker stats",
+            max=workers["max"],
+            active=workers["active"],
+            available=workers["available"],
+        )
+
+    # Queue depth is read from the run table via Runs.stats (a gRPC call to the
+    # Go core on postgres). Emitted by the API process only — the queue worker
+    # (IS_QUEUE_ENTRYPOINT) skips it. inmem skips the DB round-trip and reports
+    # nothing.
+    if IS_POSTGRES_OR_GRPC_BACKEND and not config.IS_QUEUE_ENTRYPOINT:
+        async with connect() as conn:
+            stats = await Runs.stats(conn)
+        reporter.record_gauge(GAUGE_NUM_PENDING_RUNS, stats["n_pending"])
+        reporter.record_gauge(GAUGE_NUM_RUNNING_RUNS, stats["n_running"])
+
+
+async def _collect_pool(reporter, prev_counters: dict[str, int]) -> None:
+    """Postgres + Redis pool gauges + cumulative request counters.
+
+    Postgres runtime only, recorded on **both** processes (API server and queue
+    worker) — each reports its own pools. Uses ``meta_pool_stats()``, which merges
+    the local Python pools with the Go-core pools — matching the legacy /metrics.
+    Redis stats come from the local Python pool (the Go core omits them unless it
+    has a non-cluster redis client), so a Go-core-only source would drop them.
+    """
+    # Limitation: under BG_JOB_ISOLATED_LOOPS each worker runs in its own thread with its own
+    # thread-local pg pool and redis client. This collector runs on the main
+    # thread, so meta_pool_stats() -> _get_pool()/redis_stats() only sees the main
+    # thread's pool (redis_stats() reads the global client unconditionally), and
+    # the per-thread isolated pools are NOT aggregated — so pg/redis pool gauges
+    # and the pg request counters under-report in isolated-loop mode.
+    stats = await meta_pool_stats()
+
+    pg = stats.get("postgres") or {}
+    if pg:
+        reporter.record_gauge(GAUGE_PG_POOL_MAX, pg.get("pool_max", 0))
+        reporter.record_gauge(GAUGE_PG_POOL_SIZE, pg.get("pool_size", 0))
+        reporter.record_gauge(GAUGE_PG_POOL_AVAILABLE, pg.get("pool_available", 0))
+        # Cumulative counters: record the delta since the last sample. Emit on a
+        # non-negative delta (>= 0) so the counter is created and reported from the
+        # first sample even when it is 0 — the legacy /metrics always reported
+        # these. Negative deltas (Go-core pool counter resets) are skipped to keep
+        # the OTLP counter monotonic.
+        for key, metric in (
+            ("requests_queued", COUNTER_PG_POOL_REQUESTS_QUEUED),
+            ("requests_errors", COUNTER_PG_POOL_REQUESTS_ERRORS),
+        ):
+            current = pg.get(key, 0)
+            delta = current - prev_counters.get(key, 0)
+            if delta >= 0:
+                reporter.inc_counter(metric, delta)
+            prev_counters[key] = current
+        await logger.ainfo("Postgres pool stats", **pg)
+
+    redis = stats.get("redis") or {}
+    if redis:
+        reporter.record_gauge(
+            GAUGE_REDIS_POOL_AVAILABLE, redis.get("idle_connections", 0)
+        )
+        reporter.record_gauge(GAUGE_REDIS_POOL_SIZE, redis.get("in_use_connections", 0))
+        reporter.record_gauge(GAUGE_REDIS_POOL_MAX, redis.get("max_connections", 0))
+        await logger.ainfo("Redis pool stats", **redis)
+
+
+async def _collect_once(prev_counters: dict[str, int]) -> None:
+    reporter = get_otlp_metrics_reporter()
+    if not reporter.enabled:
+        return
+
+    # Worker gauges are emitted wherever workers run; _collect_queue_and_workers
+    # adds queue depth on the API process only (postgres; inmem skips the DB
+    # round-trip).
+    try:
+        await _collect_queue_and_workers(reporter)
+    except Exception as exc:
+        await logger.awarning(
+            "metrics collector: queue/worker sample failed", exc_info=exc
+        )
+
+    # Postgres/Redis pools live in the Go core (no real pools on inmem).
+    if IS_POSTGRES_OR_GRPC_BACKEND:
+        try:
+            await _collect_pool(reporter, prev_counters)
+        except Exception as exc:
+            await logger.awarning("metrics collector: pool sample failed", exc_info=exc)
+
+
+async def collector_loop() -> None:
+    """Sample snapshot metrics into the OTLP client every STATS_INTERVAL_SECS."""
+    interval = config.STATS_INTERVAL_SECS
+    prev_counters: dict[str, int] = {}
+    await logger.ainfo("Starting OTLP metrics collector loop", interval_secs=interval)
+    try:
+        while True:
+            await _collect_once(prev_counters)
+            await asyncio.sleep(interval)
+    except asyncio.CancelledError:
+        pass