From 5a9f8798f4472469eeae4c8ae328ba397d3a0e9a Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Mon, 13 Jul 2026 08:33:36 +0200 Subject: [PATCH 1/2] LCORE-2861: Refactored observability package documentation --- src/observability/README.md | 99 ++--------------------------------- src/observability/__init__.py | 94 +++++++++++++++++++++++++++++++++ src/utils/README.md | 2 +- 3 files changed, 100 insertions(+), 95 deletions(-) diff --git a/src/observability/README.md b/src/observability/README.md index adac27a7d..6a4e966d4 100644 --- a/src/observability/README.md +++ b/src/observability/README.md @@ -1,97 +1,8 @@ -# Observability Module +# List of source files stored in `src/observability` directory -This module provides telemetry capabilities for sending inference events to external systems like Splunk HEC. +## [__init__.py](__init__.py) +Observability module for telemetry and event collection. -## Architecture +## [splunk.py](splunk.py) +Async Splunk HEC client for sending telemetry events. -``` -observability/ -├── __init__.py # Public API exports -├── splunk.py # Async Splunk HEC client -└── formats/ - ├── __init__.py # Format exports - └── rlsapi.py # rlsapi v1 event format -``` - -## Usage - -### Sending Events to Splunk - -```python -from fastapi import BackgroundTasks -from observability import send_splunk_event, build_inference_event, InferenceEventData - -# Build the event payload -event_data = InferenceEventData( - question="How do I configure SSH?", - response="To configure SSH...", - inference_time=2.34, - model="granite-3-8b-instruct", - org_id="12345678", - system_id="abc-def-123", - request_id="req_xyz789", - cla_version="CLA/0.6.0rc2", - system_os="RHEL", - system_version="9.3", - system_arch="x86_64", -) - -event = build_inference_event(event_data) - -# Queue for async sending via BackgroundTasks -background_tasks.add_task(send_splunk_event, event, "infer_with_llm") -``` - -### Source Types - -| Source Type | Description | -|-------------|-------------| -| `infer_with_llm` | Successful inference requests | -| `infer_error` | Failed inference requests | - -## Creating Custom Event Formats - -To add a new event format for a different endpoint: - -1. Create a new module in `observability/formats/`: - -```python -# observability/formats/my_endpoint.py -from dataclasses import dataclass -from typing import Any - -@dataclass -class MyEventData: - field1: str - field2: int - -def build_my_event(data: MyEventData) -> dict[str, Any]: - return { - "field1": data.field1, - "field2": data.field2, - } -``` - -2. Export from `observability/formats/__init__.py` - -3. Use with `send_splunk_event()`: - -```python -from observability import send_splunk_event -from observability.formats.my_endpoint import build_my_event, MyEventData - -event = build_my_event(MyEventData(field1="value", field2=42)) -background_tasks.add_task(send_splunk_event, event, "my_sourcetype") -``` - -## Graceful Degradation - -The Splunk client is designed to never block or fail the main request: - -- Skips sending when Splunk is disabled or not configured -- Logs warnings on HTTP errors (does not raise exceptions) -- Token is read from file on each request (supports rotation without restart) - -## Configuration - -See [docs/splunk.md](../../docs/splunk.md) for configuration options. diff --git a/src/observability/__init__.py b/src/observability/__init__.py index 65373b703..9e48dd6de 100644 --- a/src/observability/__init__.py +++ b/src/observability/__init__.py @@ -6,6 +6,100 @@ The splunk module provides a format-agnostic send_splunk_event() function. Event formats are in the formats subpackage - see formats.rlsapi for the default implementation, or create your own format module. + +## Architecture + +``` +observability/ +├── __init__.py # Public API exports +├── splunk.py # Async Splunk HEC client +└── formats/ + ├── __init__.py # Format exports + └── rlsapi.py # rlsapi v1 event format +``` + +## Usage + +### Sending Events to Splunk + +```python +from fastapi import BackgroundTasks +from observability import send_splunk_event, build_inference_event, InferenceEventData + +# Build the event payload +event_data = InferenceEventData( + question="How do I configure SSH?", + response="To configure SSH...", + inference_time=2.34, + model="granite-3-8b-instruct", + org_id="12345678", + system_id="abc-def-123", + request_id="req_xyz789", + cla_version="CLA/0.6.0rc2", + system_os="RHEL", + system_version="9.3", + system_arch="x86_64", +) + +event = build_inference_event(event_data) + +# Queue for async sending via BackgroundTasks +background_tasks.add_task(send_splunk_event, event, "infer_with_llm") +``` + +### Source Types + +| Source Type | Description | +|-------------|-------------| +| `infer_with_llm` | Successful inference requests | +| `infer_error` | Failed inference requests | + +## Creating Custom Event Formats + +To add a new event format for a different endpoint: + +1. Create a new module in `observability/formats/`: + +```python +# observability/formats/my_endpoint.py +from dataclasses import dataclass +from typing import Any + +@dataclass +class MyEventData: + field1: str + field2: int + +def build_my_event(data: MyEventData) -> dict[str, Any]: + return { + "field1": data.field1, + "field2": data.field2, + } +``` + +2. Export from `observability/formats/__init__.py` + +3. Use with `send_splunk_event()`: + +```python +from observability import send_splunk_event +from observability.formats.my_endpoint import build_my_event, MyEventData + +event = build_my_event(MyEventData(field1="value", field2=42)) +background_tasks.add_task(send_splunk_event, event, "my_sourcetype") +``` + +## Graceful Degradation + +The Splunk client is designed to never block or fail the main request: + +- Skips sending when Splunk is disabled or not configured +- Logs warnings on HTTP errors (does not raise exceptions) +- Token is read from file on each request (supports rotation without restart) + +## Configuration + +See [docs/splunk.md](../../docs/splunk.md) for configuration options. """ from observability.formats import ( diff --git a/src/utils/README.md b/src/utils/README.md index 43981be45..d79acc8f0 100644 --- a/src/utils/README.md +++ b/src/utils/README.md @@ -57,7 +57,7 @@ Utility function to dump schema with list of models into OpenAPI-compatible JSON ## [prompts.py](prompts.py) Utility functions for system prompts. -## [pydantic_ai.py](pydantic_ai.py) +## [pydantic_ai_helpers.py](pydantic_ai_helpers.py) Helpers for running Pydantic AI agents against Llama Stack (Responses API compatibility). ## [query.py](query.py) From 35577f844a8bcdd1e6d367414afa685c210a4bc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pavel=20Ti=C5=A1novsk=C3=BD?= Date: Mon, 13 Jul 2026 08:41:43 +0200 Subject: [PATCH 2/2] Update src/observability/__init__.py Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- src/observability/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/observability/__init__.py b/src/observability/__init__.py index 9e48dd6de..3b6e896d8 100644 --- a/src/observability/__init__.py +++ b/src/observability/__init__.py @@ -15,8 +15,8 @@ ├── splunk.py # Async Splunk HEC client └── formats/ ├── __init__.py # Format exports - └── rlsapi.py # rlsapi v1 event format -``` + ├── rlsapi.py # rlsapi v1 event format + └── responses.py # responses event format ## Usage