{"id":35542470,"url":"https://github.com/telemetryflow/telemetryflow-python-sdk","last_synced_at":"2026-01-13T23:36:07.215Z","repository":{"id":331318717,"uuid":"1125533848","full_name":"telemetryflow/telemetryflow-python-sdk","owner":"telemetryflow","description":"Enterprise-grade Python SDK for TelemetryFlow - the observability platform that provides unified metrics, logs, and traces collection following OpenTelemetry standards.","archived":false,"fork":false,"pushed_at":"2026-01-09T07:38:28.000Z","size":354,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T19:44:25.300Z","etag":null,"topics":["devopscorner","observability","opentelemetry","opentelemetry-python","opentelemetry-sdk","otel","telemetryflow"],"latest_commit_sha":null,"homepage":"https://www.telemetryflow.id","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telemetryflow.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":"SECURITY.md","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-12-30T22:44:43.000Z","updated_at":"2026-01-09T07:38:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/telemetryflow/telemetryflow-python-sdk","commit_stats":null,"previous_names":["telemetryflow/telemetryflow-python-sdk"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/telemetryflow/telemetryflow-python-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-python-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-python-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-python-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-python-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telemetryflow","download_url":"https://codeload.github.com/telemetryflow/telemetryflow-python-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-python-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28405304,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T21:51:37.118Z","status":"ssl_error","status_checked_at":"2026-01-13T21:45:14.585Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["devopscorner","observability","opentelemetry","opentelemetry-python","opentelemetry-sdk","otel","telemetryflow"],"created_at":"2026-01-04T05:09:46.748Z","updated_at":"2026-01-13T23:36:07.210Z","avatar_url":"https://github.com/telemetryflow.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/telemetryflow/.github/raw/main/docs/assets/tfo-logo-sdk-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/telemetryflow/.github/raw/main/docs/assets/tfo-logo-sdk-light.svg\"\u003e\n    \u003cimg src=\"https://github.com/telemetryflow/.github/raw/main/docs/assets/tfo-logo-sdk-light.svg\" alt=\"TelemetryFlow Logo\" width=\"80%\"\u003e\n  \u003c/picture\u003e\n\n  \u003ch3\u003eTelemetryFlow Python SDK\u003c/h3\u003e\n\n[![Version](https://img.shields.io/badge/Version-1.1.2-orange.svg)](CHANGELOG.md)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org)\n[![PyPI](https://img.shields.io/pypi/v/telemetryflow-python-sdk?logo=python\u0026logoColor=white\u0026label=PyPI)](https://pypi.org/project/telemetryflow-python-sdk/)\n[![OTEL SDK](https://img.shields.io/badge/OpenTelemetry_SDK-1.28.0-blueviolet)](https://opentelemetry.io/)\n[![OpenTelemetry](https://img.shields.io/badge/OTLP-100%25%20Compliant-success?logo=opentelemetry)](https://opentelemetry.io/)\n[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat\u0026logo=docker)](https://hub.docker.com/r/telemetryflow/telemetryflow-python-sdk)\n\n\u003cp align=\"center\"\u003e\n  Enterprise-grade Python SDK for \u003ca href=\"https://telemetryflow.id\"\u003eTelemetryFlow\u003c/a\u003e - the observability platform that provides unified metrics, logs, and traces collection following OpenTelemetry standards.\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **100% OTLP Compliant** | Full OpenTelemetry Protocol support |\n| **DDD Architecture** | Domain-Driven Design with clean layers |\n| **CQRS Pattern** | Command Query Responsibility Segregation |\n| **Three Signals** | Metrics, Logs, and Traces |\n| **Multiple Protocols** | gRPC (default) and HTTP |\n| **Type Safety** | Full type hints with mypy support |\n| **Framework Integrations** | Flask, FastAPI middleware |\n| **CLI Generator** | Project scaffolding tool |\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Interface Layer\"\n        A[TelemetryFlowClient]\n        B[TelemetryFlowBuilder]\n    end\n\n    subgraph \"Application Layer\"\n        C[Commands]\n        D[Queries]\n    end\n\n    subgraph \"Domain Layer\"\n        E[TelemetryConfig]\n        F[Credentials]\n    end\n\n    subgraph \"Infrastructure Layer\"\n        G[CommandHandler]\n        H[OTLPExporterFactory]\n        I[OpenTelemetry SDK]\n    end\n\n    A --\u003e C\n    B --\u003e E\n    C --\u003e G\n    G --\u003e H\n    H --\u003e I\n    E --\u003e F\n\n    style A fill:#4CAF50\n    style E fill:#2196F3\n    style G fill:#FF9800\n```\n\n## Installation\n\n```bash\npip install telemetryflow-python-sdk\n```\n\nWith optional dependencies:\n\n```bash\n# HTTP framework support (Flask, FastAPI)\npip install telemetryflow-python-sdk[http]\n\n# gRPC support\npip install telemetryflow-python-sdk[grpc]\n\n# Development tools\npip install telemetryflow-python-sdk[dev]\n\n# All extras\npip install telemetryflow-python-sdk[dev,http,grpc]\n```\n\n## Quick Start\n\n### 1. Set Environment Variables\n\n```bash\nexport TELEMETRYFLOW_API_KEY_ID=tfk_your_key_id\nexport TELEMETRYFLOW_API_KEY_SECRET=tfs_your_key_secret\nexport TELEMETRYFLOW_ENDPOINT=api.telemetryflow.id:4317\nexport TELEMETRYFLOW_SERVICE_NAME=my-python-service\nexport TELEMETRYFLOW_SERVICE_VERSION=1.0.0\nexport TELEMETRYFLOW_ENVIRONMENT=production\n```\n\n### 2. Basic Usage\n\n```python\nfrom telemetryflow import TelemetryFlowBuilder\nfrom telemetryflow.application.commands import SpanKind\n\ndef main():\n    # Create client from environment variables\n    client = TelemetryFlowBuilder().with_auto_configuration().build()\n\n    # Initialize the SDK\n    client.initialize()\n\n    try:\n        # Record metrics\n        client.increment_counter(\"http.requests.total\", attributes={\"method\": \"GET\"})\n        client.record_gauge(\"app.connections.active\", 42)\n        client.record_histogram(\"http.request.duration\", 0.125, unit=\"s\")\n\n        # Emit logs\n        client.log_info(\"Request processed\", {\"user_id\": \"123\"})\n        client.log_error(\"Database connection failed\", {\"db\": \"users\"})\n\n        # Create traces\n        with client.span(\"process_request\", SpanKind.SERVER) as span_id:\n            client.add_span_event(span_id, \"validation_complete\")\n\n            with client.span(\"database_query\", SpanKind.CLIENT) as db_span:\n                client.add_span_event(db_span, \"query_executed\", {\"rows\": 10})\n\n    finally:\n        # Always shutdown to flush pending data\n        client.shutdown()\n\nif __name__ == \"__main__\":\n    main()\n```\n\n### 3. Using Context Manager\n\n```python\nfrom telemetryflow import TelemetryFlowBuilder\n\n# Client auto-initializes and shuts down\nwith TelemetryFlowBuilder().with_auto_configuration().build() as client:\n    client.increment_counter(\"app.started\")\n    client.log_info(\"Application running\")\n```\n\n## Configuration\n\n### Builder Pattern\n\n```python\nfrom datetime import timedelta\nfrom telemetryflow import TelemetryFlowBuilder\n\nclient = (\n    TelemetryFlowBuilder()\n    # Credentials\n    .with_api_key(\"tfk_your_key_id\", \"tfs_your_key_secret\")\n\n    # Endpoint\n    .with_endpoint(\"api.telemetryflow.id:4317\")\n\n    # Service info\n    .with_service(\"my-service\", \"1.0.0\")\n    .with_service_namespace(\"platform\")\n    .with_environment(\"production\")\n\n    # Protocol\n    .with_grpc()  # or .with_http()\n    .with_insecure(False)\n\n    # Signals\n    .with_signals(metrics=True, logs=True, traces=True)\n    .with_exemplars(True)\n\n    # Advanced\n    .with_timeout(timedelta(seconds=30))\n    .with_compression(True)\n    .with_collector_id(\"collector-1\")\n    .with_custom_attribute(\"team\", \"platform\")\n\n    # Batch settings\n    .with_batch_settings(\n        timeout=timedelta(seconds=10),\n        max_size=512\n    )\n\n    # Build\n    .build()\n)\n```\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `TELEMETRYFLOW_API_KEY_ID` | Yes | - | API key ID (tfk_*) |\n| `TELEMETRYFLOW_API_KEY_SECRET` | Yes | - | API key secret (tfs_*) |\n| `TELEMETRYFLOW_ENDPOINT` | No | api.telemetryflow.id:4317 | Collector endpoint |\n| `TELEMETRYFLOW_SERVICE_NAME` | Yes | - | Service name |\n| `TELEMETRYFLOW_SERVICE_VERSION` | No | 1.0.0 | Service version |\n| `TELEMETRYFLOW_SERVICE_NAMESPACE` | No | telemetryflow | Service namespace |\n| `TELEMETRYFLOW_ENVIRONMENT` | No | production | Environment |\n| `TELEMETRYFLOW_COLLECTOR_ID` | No | - | Collector ID |\n\n## API Reference\n\n### Metrics\n\n```python\n# Counter - monotonically increasing value\nclient.increment_counter(\"requests.total\", value=1, attributes={\"endpoint\": \"/api\"})\n\n# Gauge - point-in-time value\nclient.record_gauge(\"connections.active\", 42, attributes={\"pool\": \"default\"})\n\n# Histogram - distribution of values\nclient.record_histogram(\"request.duration\", 0.125, unit=\"s\", attributes={\"method\": \"GET\"})\n\n# Generic metric\nclient.record_metric(\"custom.metric\", 100.0, unit=\"count\")\n```\n\n### Logs\n\n```python\nfrom telemetryflow.application.commands import SeverityLevel\n\n# Convenience methods\nclient.log_debug(\"Debug message\", {\"key\": \"value\"})\nclient.log_info(\"Info message\", {\"user_id\": \"123\"})\nclient.log_warn(\"Warning message\", {\"threshold\": 0.9})\nclient.log_error(\"Error message\", {\"error\": \"connection_failed\"})\n\n# Custom severity\nclient.log(\"Custom log\", SeverityLevel.FATAL, {\"critical\": True})\n```\n\n### Traces\n\n```python\nfrom telemetryflow.application.commands import SpanKind\n\n# Context manager (recommended)\nwith client.span(\"operation\", SpanKind.SERVER, {\"key\": \"value\"}) as span_id:\n    client.add_span_event(span_id, \"checkpoint\", {\"progress\": 50})\n    # work...\n\n# Manual span management\nspan_id = client.start_span(\"operation\", SpanKind.CLIENT)\ntry:\n    client.add_span_event(span_id, \"started\")\n    # work...\nexcept Exception as e:\n    client.end_span(span_id, error=e)\n    raise\nelse:\n    client.end_span(span_id)\n```\n\n### Span Kinds\n\n| Kind | Use Case |\n|------|----------|\n| `SpanKind.INTERNAL` | Internal operations (default) |\n| `SpanKind.SERVER` | Server-side request handling |\n| `SpanKind.CLIENT` | Client-side requests |\n| `SpanKind.PRODUCER` | Message queue producers |\n| `SpanKind.CONSUMER` | Message queue consumers |\n\n## Framework Integration\n\n### Flask\n\n```python\nfrom flask import Flask\nfrom telemetryflow import TelemetryFlowBuilder\nfrom telemetryflow.middleware import FlaskTelemetryMiddleware\n\napp = Flask(__name__)\n\n# Initialize client\nclient = TelemetryFlowBuilder().with_auto_configuration().build()\nclient.initialize()\n\n# Add middleware\nmiddleware = FlaskTelemetryMiddleware(\n    client,\n    excluded_paths=[\"/health\", \"/metrics\"],\n)\nmiddleware.init_app(app)\n\n@app.route(\"/\")\ndef hello():\n    return \"Hello, World!\"\n\n@app.route(\"/health\")\ndef health():\n    return {\"status\": \"healthy\"}\n```\n\n### FastAPI\n\n```python\nfrom fastapi import FastAPI\nfrom telemetryflow import TelemetryFlowBuilder\nfrom telemetryflow.middleware import FastAPITelemetryMiddleware\n\napp = FastAPI()\n\n# Initialize client\nclient = TelemetryFlowBuilder().with_auto_configuration().build()\nclient.initialize()\n\n# Add middleware\napp.add_middleware(\n    FastAPITelemetryMiddleware,\n    client=client,\n    excluded_paths=[\"/health\"],\n)\n\n@app.get(\"/\")\nasync def root():\n    return {\"message\": \"Hello, World!\"}\n\n@app.get(\"/health\")\nasync def health():\n    return {\"status\": \"healthy\"}\n```\n\n## CLI Generator\n\nGenerate project scaffolding:\n\n```bash\n# Initialize in current directory\ntelemetryflow-gen init\n\n# Generate example code\ntelemetryflow-gen example --type basic\ntelemetryflow-gen example --type http-server\n\n# Show version\ntelemetryflow-gen version\n```\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n    participant App as Application\n    participant SDK as TelemetryFlow SDK\n    participant OTEL as OpenTelemetry\n    participant TF as TelemetryFlow Backend\n\n    App-\u003e\u003eSDK: client.increment_counter()\n    SDK-\u003e\u003eSDK: Create Command\n    SDK-\u003e\u003eOTEL: Record Metric\n\n    Note over OTEL: Batch \u0026 Export\n\n    OTEL-\u003e\u003eTF: OTLP Export (gRPC/HTTP)\n    TF--\u003e\u003eOTEL: Ack\n```\n\n## Project Structure\n\n```\ntelemetryflow-python-sdk/\n├── src/telemetryflow/\n│   ├── __init__.py           # Package exports\n│   ├── client.py             # Main client\n│   ├── builder.py            # Builder pattern\n│   ├── version.py            # Version info\n│   ├── banner.py             # ASCII banners\n│   ├── py.typed              # PEP 561 marker\n│   ├── domain/               # Domain layer (DDD)\n│   │   ├── credentials.py    # Credentials value object\n│   │   └── config.py         # TelemetryConfig aggregate\n│   ├── application/          # Application layer (CQRS)\n│   │   ├── commands.py       # Command definitions\n│   │   └── queries.py        # Query definitions\n│   ├── infrastructure/       # Infrastructure layer\n│   │   ├── exporters.py      # OTLP exporters\n│   │   └── handlers.py       # Command handlers\n│   ├── middleware/           # Framework integrations\n│   │   ├── base.py\n│   │   ├── flask.py\n│   │   └── fastapi.py\n│   └── cli/                  # CLI tools\n│       └── generator.py\n├── tests/                    # Test suite\n│   ├── unit/                 # Unit tests by layer\n│   └── integration/          # Integration tests\n├── examples/                 # Example applications\n│   ├── basic/\n│   ├── http_server/\n│   ├── grpc_server/\n│   └── worker/\n├── docs/                     # Documentation\n│   ├── QUICKSTART.md\n│   ├── ARCHITECTURE.md\n│   ├── API_REFERENCE.md\n│   ├── GENERATOR.md\n│   ├── TESTING.md\n│   └── BUILD-SYSTEM.md\n├── pyproject.toml           # Project configuration\n├── Makefile                 # Build automation\n├── README.md\n├── CHANGELOG.md\n└── LICENSE\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/telemetryflow/telemetryflow-python-sdk.git\ncd telemetryflow-python-sdk\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate\n\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Commands\n\n```bash\n# Run tests\nmake test\n\n# Run with coverage\nmake test-coverage\n\n# Lint code\nmake lint\n\n# Format code\nmake format\n\n# Type check\nmake typecheck\n\n# Run all checks\nmake check\n\n# Build package\nmake build\n```\n\n### Testing\n\n```bash\n# All tests\npytest\n\n# Unit tests only\npytest tests/unit/ -v\n\n# Integration tests\npytest tests/integration/ -v -m integration\n\n# With coverage\npytest --cov=telemetryflow --cov-report=html\n```\n\n## Testing Strategy\n\n| Layer | Target Coverage | Focus |\n|-------|-----------------|-------|\n| Domain | 90%+ | Value objects, validation |\n| Application | 85%+ | Commands, queries |\n| Infrastructure | 80%+ | Handlers, exporters |\n| Client | 85%+ | Public API |\n\n## Best Practices\n\n### 1. Initialize Once\n\n```python\n# Good: Single initialization at startup\nclient = TelemetryFlowBuilder().with_auto_configuration().build()\nclient.initialize()\n\n# Bad: Creating client per request\nfor request in requests:\n    client = TelemetryFlowBuilder()...  # Don't do this!\n```\n\n### 2. Use Context Managers\n\n```python\n# Good: Automatic cleanup\nwith client.span(\"operation\") as span_id:\n    # work...\n\n# Avoid: Manual management (error-prone)\nspan_id = client.start_span(\"operation\")\n# if exception, span may not end\nclient.end_span(span_id)\n```\n\n### 3. Graceful Shutdown\n\n```python\n# Good: Always shutdown\ntry:\n    client.initialize()\n    # application logic\nfinally:\n    client.shutdown()\n\n# Better: Context manager\nwith TelemetryFlowBuilder()...build() as client:\n    # application logic\n```\n\n### 4. Meaningful Attributes\n\n```python\n# Good: Structured, low-cardinality\nclient.increment_counter(\n    \"http.requests\",\n    attributes={\n        \"http.method\": \"POST\",\n        \"http.route\": \"/api/users\",\n        \"http.status_code\": 200,\n    }\n)\n\n# Bad: High-cardinality\nclient.increment_counter(\"request\", attributes={\"url\": full_url})\n```\n\n## Security\n\n- **Never commit credentials**: Use environment variables\n- **Use TLS**: Set `with_insecure(False)` in production\n- **Rotate keys**: Regularly rotate API keys\n- **Validate inputs**: SDK validates credential format\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Quick Start](docs/QUICKSTART.md) | 5-minute setup guide |\n| [Architecture](docs/ARCHITECTURE.md) | DDD/CQRS design with diagrams |\n| [API Reference](docs/API_REFERENCE.md) | Complete API documentation |\n| [Generator](docs/GENERATOR.md) | CLI tool guide |\n| [Testing](docs/TESTING.md) | Testing best practices |\n| [Build System](docs/BUILD-SYSTEM.md) | Development workflow |\n\n## Requirements\n\n- Python 3.12+\n- OpenTelemetry SDK 1.28.0+\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE) for details.\n\n## Links\n\n- [TelemetryFlow](https://telemetryflow.id)\n- [Documentation](https://docs.telemetryflow.id)\n- [Go SDK](https://github.com/telemetryflow/telemetryflow-go-sdk)\n- [OpenTelemetry](https://opentelemetry.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetryflow%2Ftelemetryflow-python-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelemetryflow%2Ftelemetryflow-python-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetryflow%2Ftelemetryflow-python-sdk/lists"}