{"id":31027255,"url":"https://github.com/aleph-alpha/pharia-telemetry","last_synced_at":"2026-02-19T12:03:12.806Z","repository":{"id":314128191,"uuid":"1053356159","full_name":"Aleph-Alpha/pharia-telemetry","owner":"Aleph-Alpha","description":"Python library which provides shared telemetry code","archived":false,"fork":false,"pushed_at":"2025-09-10T16:15:27.000Z","size":326,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-10T20:19:27.386Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Aleph-Alpha.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T10:37:07.000Z","updated_at":"2025-09-10T16:15:10.000Z","dependencies_parsed_at":"2025-09-10T20:22:09.966Z","dependency_job_id":"b6e5b304-8b92-4806-861f-cd9e7d880c87","html_url":"https://github.com/Aleph-Alpha/pharia-telemetry","commit_stats":null,"previous_names":["aleph-alpha/pharia-telemetry"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Aleph-Alpha/pharia-telemetry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aleph-Alpha%2Fpharia-telemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aleph-Alpha%2Fpharia-telemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aleph-Alpha%2Fpharia-telemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aleph-Alpha%2Fpharia-telemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Aleph-Alpha","download_url":"https://codeload.github.com/Aleph-Alpha/pharia-telemetry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aleph-Alpha%2Fpharia-telemetry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274976845,"owners_count":25384285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-13T19:00:08.117Z","updated_at":"2026-02-19T12:03:12.799Z","avatar_url":"https://github.com/Aleph-Alpha.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pharia Telemetry\n\n[![Python](https://img.shields.io/pypi/pyversions/pharia-telemetry.svg)](https://pypi.org/project/pharia-telemetry/)\n[![PyPI version](https://img.shields.io/pypi/v/pharia-telemetry.svg)](https://pypi.org/project/pharia-telemetry/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/aleph-alpha/pharia-telemetry/workflows/CI/badge.svg)](https://github.com/aleph-alpha/pharia-telemetry/actions/workflows/ci.yml)\n![Coverage](https://img.shields.io/badge/coverage-check%20latest%20PR-blue)\n\n**A clean, minimal OpenTelemetry foundation library for Pharia services providing observability, tracing, and context propagation utilities.**\n\n## 🎯 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## 📦 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@\u003ccommit-sha\u003e\"\n\n# SSH (if you have SSH keys configured)\npip install \"pharia-telemetry @ git+ssh://git@github.com/aleph-alpha/pharia-telemetry.git@\u003ccommit-sha\u003e\"\n\n# With optional extras\npip install \"pharia-telemetry[structlog] @ git+https://github.com/aleph-alpha/pharia-telemetry.git@\u003ccommit-sha\u003e\"\n```\n\nIn requirements files (PEP 508):\n\n```\npharia-telemetry @ git+https://github.com/aleph-alpha/pharia-telemetry.git@\u003ccommit-sha\u003e\npharia-telemetry[structlog] @ git+https://github.com/aleph-alpha/pharia-telemetry.git@\u003ccommit-sha\u003e\n```\n\n## 🚀 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## 🎯 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## 📚 Documentation Guide\n\nChoose your path based on what you need:\n\n### 🆕 New to pharia-telemetry?\n**Start here** → [**Getting Started Guide**](docs/getting-started.md)\n- Basic setup and first examples\n- Understanding the concepts\n- Your first instrumented service\n\n### 🔌 Want automatic instrumentation?\n**Go to** → [**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### 🛠️ Need manual control?\n**See** → [**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### 🧳 Working with context propagation?\n**Read** → [**Baggage \u0026 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### 📊 Setting up logging?\n**Check** → [**Structured Logging Guide**](docs/structured-logging.md)\n- Automatic trace correlation\n- Log configuration patterns\n- Integration with structlog\n\n### 🤖 Building GenAI applications?\n**Visit** → [**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### ⚙️ Need advanced configuration?\n**Visit** → [**Configuration Guide**](docs/configuration.md)\n- Environment variables\n- OTLP exporter setup\n- Custom resource attributes\n- Production deployment\n\n### 🏗️ Building integrations?\n**Browse** → [**Integration Examples**](docs/integration-examples.md)\n- Complete FastAPI service\n- Microservice communication\n- Background task processing\n- Real-world patterns\n\n### 🐛 Having issues?\n**Try** → [**Troubleshooting Guide**](docs/troubleshooting.md)\n- Common problems and solutions\n- Debug techniques\n- Performance considerations\n\n## 🌟 Core Features\n\n- **🔬 OpenTelemetry Integration**: Minimal setup utilities for distributed tracing\n- **🧳 Baggage Management**: Context propagation across service boundaries\n- **📊 Structured Logging**: Automatic trace correlation for log records\n- **🤖 Smart GenAI Spans**: Auto-detecting sync/async convenience functions for AI operations\n- **🔧 Production Ready**: Graceful degradation when OpenTelemetry is unavailable\n- **📈 Pharia Standards**: Standardized constants and conventions across all services\n- **🎯 Focused API**: Clean, intuitive functions for common use cases\n\n## 🏛️ Architecture\n\n```\n┌─────────────────────────────────────────┐\n│         Your Application + Auto         │\n│           Instrumentation              │\n├─────────────────────────────────────────┤\n│        pharia-telemetry Foundation      │\n│     (Propagators, Baggage, Logging)     │\n├─────────────────────────────────────────┤\n│           OpenTelemetry SDK             │\n├─────────────────────────────────────────┤\n│        OTLP Exporters \u0026 Backend        │\n└─────────────────────────────────────────┘\n```\n\n## 🔍 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## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## 📞 Support\n\n- 📧 **Email**: conrad.poepke@aleph-alpha.com\n- 🐛 **Issues**: [GitHub Issues](https://github.com/aleph-alpha/pharia-telemetry/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faleph-alpha%2Fpharia-telemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faleph-alpha%2Fpharia-telemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faleph-alpha%2Fpharia-telemetry/lists"}