# Pharia Telemetry
[](https://pypi.org/project/pharia-telemetry/)
[](https://pypi.org/project/pharia-telemetry/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/aleph-alpha/pharia-telemetry/actions/workflows/ci.yml)
**A clean, minimal OpenTelemetry foundation library for Pharia services providing observability, tracing, and context propagation utilities.**
## 🎯 What is pharia-telemetry?
`pharia-telemetry` provides a **simple, focused foundation** for observability in Pharia services:
- **Context Propagation**: User and session context flows automatically across all service calls
- **Structured Logging**: Logs automatically include trace IDs and user context
- **OpenTelemetry Setup**: Minimal, high-level setup for distributed tracing
- **Standardized Constants**: Clean, namespaced constants for consistent telemetry
**Key Principle**: `pharia-telemetry` handles the foundation with minimal API surface, you add framework-specific auto-instrumentation.
## 📦 Installation
Requires Python 3.10+.
```bash
# Basic installation
pip install pharia-telemetry
# With structlog support (for structured logging)
pip install pharia-telemetry[structlog]
```
### Install from GitHub (pinned to commit)
For services that depend on a specific commit from the GitHub repo, use a direct VCS reference:
```bash
# HTTPS (recommended)
pip install "pharia-telemetry @ git+https://github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>"
# SSH (if you have SSH keys configured)
pip install "pharia-telemetry @ git+ssh://git@github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>"
# With optional extras
pip install "pharia-telemetry[structlog] @ git+https://github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>"
```
In requirements files (PEP 508):
```
pharia-telemetry @ git+https://github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>
pharia-telemetry[structlog] @ git+https://github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>
```
## 🚀 30-Second Setup
```python
from pharia_telemetry import setup_telemetry, constants, set_baggage_item
# 1. One-line setup
setup_telemetry("my-service", service_version="1.0.0")
# 2. Set context that flows everywhere
set_baggage_item(constants.Baggage.USER_ID, "user-123")
# 3. Add framework instrumentation (optional)
# FastAPIInstrumentor.instrument_app(app) # for FastAPI
# SQLAlchemyInstrumentor().instrument() # for databases
```
**Result**: Your service now has distributed tracing with user context flowing through all operations!
## 🎯 Clean API Design
pharia-telemetry features a **clean, focused API** designed for ease of use:
```python
from pharia_telemetry import (
# Core setup (essential)
setup_telemetry, # One-function setup
# GenAI instrumentation (most users)
create_chat_span, # Smart sync/async chat spans
create_embeddings_span, # Smart sync/async embeddings spans
create_tool_execution_span,# Smart sync/async tool spans
set_genai_span_usage, # Token usage tracking
set_genai_span_response, # Response metadata
# Context propagation (advanced)
set_baggage_item, # Set context for propagation
get_baggage_item, # Get propagated context
# Logging integration (optional)
create_context_injector, # Custom logging integration
)
```
## 📚 Documentation Guide
Choose your path based on what you need:
### 🆕 New to pharia-telemetry?
**Start here** → [**Getting Started Guide**](docs/getting-started.md)
- Basic setup and first examples
- Understanding the concepts
- Your first instrumented service
### 🔌 Want automatic instrumentation?
**Go to** → [**Auto-Instrumentation Guide**](docs/auto-instrumentation.md)
- Available instrumentation packages
- FastAPI, SQLAlchemy, HTTPX setup
- When auto-instrumentation works (and when it doesn't)
### 🛠️ Need manual control?
**See** → [**Manual Instrumentation Guide**](docs/manual-instrumentation.md)
- SSE streaming issues and solutions
- HTTP/2 compatibility problems
- Custom span management
- Performance optimization
### 🧳 Working with context propagation?
**Read** → [**Baggage & Context Guide**](docs/baggage-and-context.md)
- User and session context
- Cross-service correlation
- Standardized baggage keys
- Custom context patterns
### 📊 Setting up logging?
**Check** → [**Structured Logging Guide**](docs/structured-logging.md)
- Automatic trace correlation
- Log configuration patterns
- Integration with structlog
### 🤖 Building GenAI applications?
**Visit** → [**GenAI Spans Guide**](docs/genai-spans.md)
- OpenTelemetry semantic conventions for AI
- Automatic span attributes for models
- Token usage tracking
- Agent and tool instrumentation
### ⚙️ Need advanced configuration?
**Visit** → [**Configuration Guide**](docs/configuration.md)
- Environment variables
- OTLP exporter setup
- Custom resource attributes
- Production deployment
### 🏗️ Building integrations?
**Browse** → [**Integration Examples**](docs/integration-examples.md)
- Complete FastAPI service
- Microservice communication
- Background task processing
- Real-world patterns
### 🐛 Having issues?
**Try** → [**Troubleshooting Guide**](docs/troubleshooting.md)
- Common problems and solutions
- Debug techniques
- Performance considerations
## 🌟 Core Features
- **🔬 OpenTelemetry Integration**: Minimal setup utilities for distributed tracing
- **🧳 Baggage Management**: Context propagation across service boundaries
- **📊 Structured Logging**: Automatic trace correlation for log records
- **🤖 Smart GenAI Spans**: Auto-detecting sync/async convenience functions for AI operations
- **🔧 Production Ready**: Graceful degradation when OpenTelemetry is unavailable
- **📈 Pharia Standards**: Standardized constants and conventions across all services
- **🎯 Focused API**: Clean, intuitive functions for common use cases
## 🏛️ Architecture
```
┌─────────────────────────────────────────┐
│ Your Application + Auto │
│ Instrumentation │
├─────────────────────────────────────────┤
│ pharia-telemetry Foundation │
│ (Propagators, Baggage, Logging) │
├─────────────────────────────────────────┤
│ OpenTelemetry SDK │
├─────────────────────────────────────────┤
│ OTLP Exporters & Backend │
└─────────────────────────────────────────┘
```
## 🔍 Quick Examples
### Context Propagation
```python
from pharia_telemetry import constants, set_baggage_item
# Set once, flows everywhere
set_baggage_item(constants.Baggage.USER_ID, "user-123")
set_baggage_item(constants.Baggage.SESSION_ID, "session-456")
```
### Structured Logging
```python
import structlog
from pharia_telemetry import add_context_to_logs
# Easy integration with any logging framework
injector = add_context_to_logs("structlog")
structlog.configure(processors=[
injector, # Adds trace_id + baggage automatically
structlog.processors.JSONRenderer(),
])
```
### GenAI Operations
```python
from pharia_telemetry import create_chat_span, create_embeddings_span
from pharia_telemetry.sem_conv.gen_ai import GenAI
# Smart convenience functions that auto-detect sync/async context
with create_chat_span(
model="llama-3.1-8B",
agent_id=GenAI.Values.PhariaAgentId.QA_CHAT,
conversation_id="conv-123"
) as span:
# Works in both sync and async contexts
pass
# Also works seamlessly in async contexts
async with create_embeddings_span(model="text-embedding-3-small") as span:
# Automatic context detection
pass
```
### Clean Constants Structure
```python
from pharia_telemetry import constants
# Namespaced and organized
user_id = constants.Baggage.USER_ID # "app.user.id"
qa_chat = constants.Baggage.Values.UserIntent.QA_CHAT # "pharia_qa_chat"
# GenAI constants in separate module
model = constants.GenAI.REQUEST_MODEL # "gen_ai.request.model"
chat_op = constants.GenAI.Values.OperationName.CHAT # "chat"
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## 📞 Support
- 📧 **Email**: conrad.poepke@aleph-alpha.com
- 🐛 **Issues**: [GitHub Issues](https://github.com/aleph-alpha/pharia-telemetry/issues)
Raw data
{
"_id": null,
"home_page": null,
"name": "pharia-telemetry",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "logging, metrics, observability, opentelemetry, telemetry, tracing",
"author": null,
"author_email": "Aleph Alpha Engineering <engineering@aleph-alpha.com>",
"download_url": "https://files.pythonhosted.org/packages/58/9b/3cf75bdd379f08df73ce3035a5cf9248c786c50d999b88bd307c1f9247af/pharia_telemetry-0.1.1.tar.gz",
"platform": null,
"description": "# Pharia Telemetry\n\n[](https://pypi.org/project/pharia-telemetry/)\n[](https://pypi.org/project/pharia-telemetry/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/aleph-alpha/pharia-telemetry/actions/workflows/ci.yml)\n\n\n**A clean, minimal OpenTelemetry foundation library for Pharia services providing observability, tracing, and context propagation utilities.**\n\n## \ud83c\udfaf What is pharia-telemetry?\n\n`pharia-telemetry` provides a **simple, focused foundation** for observability in Pharia services:\n- **Context Propagation**: User and session context flows automatically across all service calls\n- **Structured Logging**: Logs automatically include trace IDs and user context\n- **OpenTelemetry Setup**: Minimal, high-level setup for distributed tracing\n- **Standardized Constants**: Clean, namespaced constants for consistent telemetry\n\n**Key Principle**: `pharia-telemetry` handles the foundation with minimal API surface, you add framework-specific auto-instrumentation.\n\n## \ud83d\udce6 Installation\n\nRequires Python 3.10+.\n\n```bash\n# Basic installation\npip install pharia-telemetry\n\n# With structlog support (for structured logging)\npip install pharia-telemetry[structlog]\n```\n\n### Install from GitHub (pinned to commit)\n\nFor services that depend on a specific commit from the GitHub repo, use a direct VCS reference:\n\n```bash\n# HTTPS (recommended)\npip install \"pharia-telemetry @ git+https://github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>\"\n\n# SSH (if you have SSH keys configured)\npip install \"pharia-telemetry @ git+ssh://git@github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>\"\n\n# With optional extras\npip install \"pharia-telemetry[structlog] @ git+https://github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>\"\n```\n\nIn requirements files (PEP 508):\n\n```\npharia-telemetry @ git+https://github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>\npharia-telemetry[structlog] @ git+https://github.com/aleph-alpha/pharia-telemetry.git@<commit-sha>\n```\n\n## \ud83d\ude80 30-Second Setup\n\n```python\nfrom pharia_telemetry import setup_telemetry, constants, set_baggage_item\n\n# 1. One-line setup\nsetup_telemetry(\"my-service\", service_version=\"1.0.0\")\n\n# 2. Set context that flows everywhere\nset_baggage_item(constants.Baggage.USER_ID, \"user-123\")\n\n# 3. Add framework instrumentation (optional)\n# FastAPIInstrumentor.instrument_app(app) # for FastAPI\n# SQLAlchemyInstrumentor().instrument() # for databases\n```\n\n**Result**: Your service now has distributed tracing with user context flowing through all operations!\n\n## \ud83c\udfaf Clean API Design\n\npharia-telemetry features a **clean, focused API** designed for ease of use:\n\n```python\nfrom pharia_telemetry import (\n # Core setup (essential)\n setup_telemetry, # One-function setup\n\n # GenAI instrumentation (most users)\n create_chat_span, # Smart sync/async chat spans\n create_embeddings_span, # Smart sync/async embeddings spans\n create_tool_execution_span,# Smart sync/async tool spans\n set_genai_span_usage, # Token usage tracking\n set_genai_span_response, # Response metadata\n\n # Context propagation (advanced)\n set_baggage_item, # Set context for propagation\n get_baggage_item, # Get propagated context\n\n # Logging integration (optional)\n create_context_injector, # Custom logging integration\n)\n```\n\n## \ud83d\udcda Documentation Guide\n\nChoose your path based on what you need:\n\n### \ud83c\udd95 New to pharia-telemetry?\n**Start here** \u2192 [**Getting Started Guide**](docs/getting-started.md)\n- Basic setup and first examples\n- Understanding the concepts\n- Your first instrumented service\n\n### \ud83d\udd0c Want automatic instrumentation?\n**Go to** \u2192 [**Auto-Instrumentation Guide**](docs/auto-instrumentation.md)\n- Available instrumentation packages\n- FastAPI, SQLAlchemy, HTTPX setup\n- When auto-instrumentation works (and when it doesn't)\n\n### \ud83d\udee0\ufe0f Need manual control?\n**See** \u2192 [**Manual Instrumentation Guide**](docs/manual-instrumentation.md)\n- SSE streaming issues and solutions\n- HTTP/2 compatibility problems\n- Custom span management\n- Performance optimization\n\n### \ud83e\uddf3 Working with context propagation?\n**Read** \u2192 [**Baggage & Context Guide**](docs/baggage-and-context.md)\n- User and session context\n- Cross-service correlation\n- Standardized baggage keys\n- Custom context patterns\n\n### \ud83d\udcca Setting up logging?\n**Check** \u2192 [**Structured Logging Guide**](docs/structured-logging.md)\n- Automatic trace correlation\n- Log configuration patterns\n- Integration with structlog\n\n### \ud83e\udd16 Building GenAI applications?\n**Visit** \u2192 [**GenAI Spans Guide**](docs/genai-spans.md)\n- OpenTelemetry semantic conventions for AI\n- Automatic span attributes for models\n- Token usage tracking\n- Agent and tool instrumentation\n\n### \u2699\ufe0f Need advanced configuration?\n**Visit** \u2192 [**Configuration Guide**](docs/configuration.md)\n- Environment variables\n- OTLP exporter setup\n- Custom resource attributes\n- Production deployment\n\n### \ud83c\udfd7\ufe0f Building integrations?\n**Browse** \u2192 [**Integration Examples**](docs/integration-examples.md)\n- Complete FastAPI service\n- Microservice communication\n- Background task processing\n- Real-world patterns\n\n### \ud83d\udc1b Having issues?\n**Try** \u2192 [**Troubleshooting Guide**](docs/troubleshooting.md)\n- Common problems and solutions\n- Debug techniques\n- Performance considerations\n\n## \ud83c\udf1f Core Features\n\n- **\ud83d\udd2c OpenTelemetry Integration**: Minimal setup utilities for distributed tracing\n- **\ud83e\uddf3 Baggage Management**: Context propagation across service boundaries\n- **\ud83d\udcca Structured Logging**: Automatic trace correlation for log records\n- **\ud83e\udd16 Smart GenAI Spans**: Auto-detecting sync/async convenience functions for AI operations\n- **\ud83d\udd27 Production Ready**: Graceful degradation when OpenTelemetry is unavailable\n- **\ud83d\udcc8 Pharia Standards**: Standardized constants and conventions across all services\n- **\ud83c\udfaf Focused API**: Clean, intuitive functions for common use cases\n\n## \ud83c\udfdb\ufe0f Architecture\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Your Application + Auto \u2502\n\u2502 Instrumentation \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 pharia-telemetry Foundation \u2502\n\u2502 (Propagators, Baggage, Logging) \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 OpenTelemetry SDK \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 OTLP Exporters & Backend \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## \ud83d\udd0d Quick Examples\n\n### Context Propagation\n```python\nfrom pharia_telemetry import constants, set_baggage_item\n\n# Set once, flows everywhere\nset_baggage_item(constants.Baggage.USER_ID, \"user-123\")\nset_baggage_item(constants.Baggage.SESSION_ID, \"session-456\")\n```\n\n### Structured Logging\n```python\nimport structlog\nfrom pharia_telemetry import add_context_to_logs\n\n# Easy integration with any logging framework\ninjector = add_context_to_logs(\"structlog\")\nstructlog.configure(processors=[\n injector, # Adds trace_id + baggage automatically\n structlog.processors.JSONRenderer(),\n])\n```\n\n### GenAI Operations\n```python\nfrom pharia_telemetry import create_chat_span, create_embeddings_span\nfrom pharia_telemetry.sem_conv.gen_ai import GenAI\n\n# Smart convenience functions that auto-detect sync/async context\nwith create_chat_span(\n model=\"llama-3.1-8B\",\n agent_id=GenAI.Values.PhariaAgentId.QA_CHAT,\n conversation_id=\"conv-123\"\n) as span:\n # Works in both sync and async contexts\n pass\n\n# Also works seamlessly in async contexts\nasync with create_embeddings_span(model=\"text-embedding-3-small\") as span:\n # Automatic context detection\n pass\n```\n\n### Clean Constants Structure\n```python\nfrom pharia_telemetry import constants\n\n# Namespaced and organized\nuser_id = constants.Baggage.USER_ID # \"app.user.id\"\nqa_chat = constants.Baggage.Values.UserIntent.QA_CHAT # \"pharia_qa_chat\"\n\n# GenAI constants in separate module\nmodel = constants.GenAI.REQUEST_MODEL # \"gen_ai.request.model\"\nchat_op = constants.GenAI.Values.OperationName.CHAT # \"chat\"\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## \ud83d\udcde Support\n\n- \ud83d\udce7 **Email**: conrad.poepke@aleph-alpha.com\n- \ud83d\udc1b **Issues**: [GitHub Issues](https://github.com/aleph-alpha/pharia-telemetry/issues)\n",
"bugtrack_url": null,
"license": null,
"summary": "Telemetry utilities and shared components for Pharia projects",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://github.com/aleph-alpha/pharia-telemetry/blob/main/CHANGELOG.md",
"Documentation": "https://pharia-telemetry.readthedocs.io",
"Homepage": "https://github.com/aleph-alpha/pharia-telemetry",
"Issues": "https://github.com/aleph-alpha/pharia-telemetry/issues",
"Repository": "https://github.com/aleph-alpha/pharia-telemetry"
},
"split_keywords": [
"logging",
" metrics",
" observability",
" opentelemetry",
" telemetry",
" tracing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7747990174780b6abbfe78d0df17f51820d195e79b267382a65f23aea2343748",
"md5": "c80a051b4019ea458fbb3efc365c3943",
"sha256": "ebbddaa5f41edd2f121eff38cf217fc5a9e00154b30894810f0ce0cbdbff493e"
},
"downloads": -1,
"filename": "pharia_telemetry-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c80a051b4019ea458fbb3efc365c3943",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 27655,
"upload_time": "2025-09-11T07:26:30",
"upload_time_iso_8601": "2025-09-11T07:26:30.936927Z",
"url": "https://files.pythonhosted.org/packages/77/47/990174780b6abbfe78d0df17f51820d195e79b267382a65f23aea2343748/pharia_telemetry-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "589b3cf75bdd379f08df73ce3035a5cf9248c786c50d999b88bd307c1f9247af",
"md5": "629f0667e522ed81d241342c2fd76718",
"sha256": "217a353aff4119eb1e9c71d49064f1bae58faa9477dab77a526e393bf04b2b16"
},
"downloads": -1,
"filename": "pharia_telemetry-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "629f0667e522ed81d241342c2fd76718",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 77462,
"upload_time": "2025-09-11T07:26:32",
"upload_time_iso_8601": "2025-09-11T07:26:32.573154Z",
"url": "https://files.pythonhosted.org/packages/58/9b/3cf75bdd379f08df73ce3035a5cf9248c786c50d999b88bd307c1f9247af/pharia_telemetry-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 07:26:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aleph-alpha",
"github_project": "pharia-telemetry",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pharia-telemetry"
}
JSON
