<div align="center">
# 🐍📡 `pyvider.telemetry`
**Beautiful, performant, structured logging for Python.**
Modern structured logging built on `structlog` with emoji-enhanced visual parsing and semantic Domain-Action-Status patterns.
[](https://github.com/astral-sh/uv)
[](https://pypi.org/project/pyvider-telemetry/)
[](https://pypi.org/project/pyvider-telemetry/)
[](https://pepy.tech/project/pyvider-telemetry)
[](https://github.com/provide-io/pyvider-telemetry/actions/workflows/ci.yml)
[](https://codecov.io/gh/provide-io/pyvider-telemetry)
[](https://mypy.readthedocs.io/)
[](https://github.com/astral-sh/ruff)
<!-- Dependencies & Performance -->
[](https://www.structlog.org/)
[](https://www.attrs.org/)
[](README.md#performance)
[](https://opensource.org/license/apache-2-0)
---
**Make your logs beautiful and meaningful!** `pyvider.telemetry` transforms your application logging with visual emoji prefixes, semantic Domain-Action-Status patterns, and high-performance structured output. Perfect for development debugging, production monitoring, and everything in between.
</div>
## 🤔 Why `pyvider.telemetry`?
* **🎨 Visual Log Parsing:** Emoji prefixes based on logger names and semantic context make logs instantly scannable
* **📊 Semantic Structure:** **(New!)** Extensible Semantic Layers for domains like LLMs, HTTP, and Databases, with a fallback to the classic Domain-Action-Status (DAS) pattern.
* **⚡ High Performance:** Benchmarked >14,000 msg/sec (see details below)
* **🔧 Zero Configuration:** Works beautifully out of the box, configurable via environment variables or code
* **🎯 Developer Experience:** Thread-safe, async-ready, with comprehensive type hints for Python 3.13+
## ✨ Features
* **🎨 Emoji-Enhanced Logging:**
* **Logger Name Prefixes:** `🔑 User authentication successful` (auth module)
* **(New!) Semantic Layer Prefixes:** `[🤖][✍️][👍] LLM response generated` (llm-generation-success)
* **Custom TRACE Level:** Ultra-verbose debugging with `👣` visual markers
* **📈 Production Ready:**
* **High Performance:** >14,000 messages/second throughput (average ~40,000 msg/sec)
* **Thread Safe:** Concurrent logging from multiple threads
* **Async Support:** Native async/await compatibility
* **Memory Efficient:** Optimized emoji caching and processor chains
* **⚙️ Flexible Configuration:**
* **Multiple Formats:** JSON for production, key-value for development
* **Module-Level Filtering:** Different log levels per component
* **Environment Variables:** Zero-code configuration options
* **Service Identification:** Automatic service name injection
* **🏗️ Modern Python:**
* **Python 3.13+ Exclusive:** Latest language features and typing
* **Built with `attrs`:** Immutable, validated configuration objects
* **Structlog Foundation:** Industry-standard structured logging
## 🚀 Installation
Requires Python 3.13 or later.
```bash
pip install pyvider-telemetry
```
## 💡 Quick Start
### Basic Usage
```python
from pyvider.telemetry import setup_telemetry, logger
# Initialize with sensible defaults
setup_telemetry()
# Start logging immediately
logger.info("Application started", version="1.0.0")
logger.debug("Debug information", component="auth")
logger.error("Something went wrong", error_code="E123")
# Create component-specific loggers
auth_logger = logger.get_logger("auth.service")
auth_logger.info("User login attempt", user_id=12345)
# Output: 🔑 User login attempt user_id=12345
```
### 🏗️ Semantic Logging with Layers
Go beyond the basic DAS pattern with extensible, schema-driven logging. Semantic Layers allow you to define structured logging conventions for specific domains (like LLMs, HTTP, or Databases) and automatically get rich, contextual emoji prefixes.
**Example: Using the built-in `llm` layer**
First, enable the layer in your configuration:
```python
from pyvider.telemetry import setup_telemetry, TelemetryConfig, LoggingConfig
# Enable the 'llm' semantic layer
config = TelemetryConfig(
logging=LoggingConfig(enabled_semantic_layers=["llm"])
)
setup_telemetry(config)
```
Now, log events using the layer's defined keys (like `llm.provider`, `llm.task`, `llm.outcome`):
```python
from pyvider.telemetry import logger
# Log a successful LLM generation task
logger.info(
"LLM response generated",
**{
"llm.provider": "openai",
"llm.task": "generation",
"llm.outcome": "success",
"llm.model": "gpt-4o",
"duration_ms": 1230,
"llm.output.tokens": 250,
}
)
# Output: [🤖][✍️][👍] LLM response generated duration_ms=1230 llm.output.tokens=250
# Log a rate-limiting event from another provider
logger.warning(
"LLM call failed",
**{
"llm.provider": "anthropic",
"llm.task": "chat",
"llm.outcome": "rate_limit",
"llm.model": "claude-3-opus",
}
)
# Output: [📚][💬][⏳] LLM call failed
```
- **How it works:** The `llm` layer maps the `llm.provider` key to provider emojis (🤖 for openai, 📚 for anthropic), `llm.task` to task emojis (✍️ for generation), and `llm.outcome` to outcome emojis (👍 for success).
- **Extensible:** You can define your own custom layers and emoji sets for your application's specific domains!
- **Legacy DAS:** The original `domain`, `action`, `status` keys still work as a fallback if no semantic layers are active.
### Custom Configuration
```python
from pyvider.telemetry import setup_telemetry, TelemetryConfig, LoggingConfig
config = TelemetryConfig(
service_name="my-microservice",
logging=LoggingConfig(
default_level="INFO",
console_formatter="json", # JSON for production
# Enable built-in layers for HTTP and Database logging
enabled_semantic_layers=["http", "database"],
module_levels={
"auth": "DEBUG", # Verbose auth logging
"database": "ERROR", # Only DB errors
"external.api": "WARNING", # Minimal third-party noise
}
)
)
setup_telemetry(config)
```
### Environment Variable Configuration
```bash
export PYVIDER_SERVICE_NAME="my-service"
export PYVIDER_LOG_LEVEL="INFO"
export PYVIDER_LOG_CONSOLE_FORMATTER="json"
export PYVIDER_LOG_MODULE_LEVELS="auth:DEBUG,db:ERROR"
# New: Enable semantic layers via environment
export PYVIDER_LOG_ENABLED_SEMANTIC_LAYERS="llm,http"
```
```python
from pyvider.telemetry import setup_telemetry, TelemetryConfig
# Automatically loads from environment
setup_telemetry(TelemetryConfig.from_env())
```
### Exception Logging
```python
try:
risky_operation()
except Exception:
logger.exception("Operation failed",
operation="user_registration",
user_id=123)
# Automatically includes full traceback
```
### Ultra-Verbose TRACE Logging
```python
from pyvider.telemetry import setup_telemetry, logger, TelemetryConfig, LoggingConfig
# Enable TRACE level for deep debugging
config = TelemetryConfig(
logging=LoggingConfig(default_level="TRACE")
)
setup_telemetry(config)
logger.trace("Entering function", function="authenticate_user")
logger.trace("Token validation details",
token_type="bearer", expires_in=3600)
```
## 📊 Performance
`pyvider.telemetry` is designed for high-throughput production environments:
| Scenario | Performance | Notes |
|----------|-------------|-------|
| **Basic Logging** | ~40,000 msg/sec | Key-value format with emojis |
| **JSON Output** | ~38,900 msg/sec | Structured production format |
| **Multithreaded** | ~39,800 msg/sec | Concurrent logging |
| **Level Filtering** | ~68,100 msg/sec | Efficiently filters by level |
| **Large Payloads** | ~14,200 msg/sec | Logging with larger event data |
| **Async Logging** | ~43,400 msg/sec | Logging from async code |
**Overall Average Throughput:** ~40,800 msg/sec
**Peak Throughput:** ~68,100 msg/sec
Run benchmarks yourself:
```bash
python scripts/benchmark_performance.py
python scripts/extreme_performance.py
```
## 🎨 Emoji Reference
The emoji system is now driven by **Semantic Layers**. The active layers determine which log keys produce emoji prefixes.
### Viewing the Active Emoji Contract
To see the complete emoji mappings for your **current configuration** (including any custom layers), run the following command. This is the best way to see which emojis are active.
```bash
# This will print the full emoji matrix for your active configuration
export PYVIDER_SHOW_EMOJI_MATRIX=true
python -c "from pyvider.telemetry.logger.emoji_matrix import show_emoji_matrix; show_emoji_matrix()"
```
### Built-in Layer Emojis (Examples)
- **`llm` Layer:**
- **Provider:** `llm.provider` -> `🤖` (openai), `📚` (anthropic), `🦙` (meta)
- **Task:** `llm.task` -> `✍️` (generation), `💬` (chat), `🛠️` (tool_use)
- **Outcome:** `llm.outcome` -> `👍` (success), `🔥` (error), `⏳` (rate_limit)
- **`http` Layer:**
- **Method:** `http.method` -> `📥` (get), `📤` (post), `🗑️` (delete)
- **Status Class:** `http.status_class` -> `✅` (2xx), `⚠️CLIENT` (4xx), `🔥SERVER` (5xx)
### Legacy DAS Emojis (Fallback)
These emojis are used when no semantic layers are active and you use the `domain`, `action`, and `status` keys.
- **Domain Emojis (Primary):** `🔑` auth, `🗄️` database, `🌐` network, `⚙️` system
- **Action Emojis (Secondary):** `➡️` login, `🔗` connect, `📤` send, `🔍` query
- **Status Emojis (Tertiary):** `✅` success, `🔥` error, `⚠️` warning, `⏳` attempt
## 🔧 Advanced Usage
### Async Applications
```python
import asyncio
from pyvider.telemetry import setup_telemetry, logger, shutdown_pyvider_telemetry
async def main():
setup_telemetry()
# Your async application code
logger.info("Async app started")
# Graceful shutdown
await shutdown_pyvider_telemetry()
asyncio.run(main())
```
<!-- NEW SECTION -->
### Timing Code Blocks
Easily log the duration and outcome of any code block using the `timed_block` context manager. It automatically handles success and failure cases.
```python
import time
from pyvider.telemetry import logger, timed_block
# Successful operation
with timed_block(logger, "Data processing task", task_id="abc-123"):
time.sleep(0.05) # Simulate work
# Output: Data processing task task_id=abc-123 outcome=success duration_ms=50
# Failing operation
try:
with timed_block(logger, "Database query", table="users"):
raise ValueError("Connection refused")
except ValueError:
pass # Exception is re-raised and caught here
# Output: Database query table=users outcome=error error.message='Connection refused' error.type=ValueError duration_ms=...
```
<!-- END NEW SECTION -->
### Production Configuration
```python
production_config = TelemetryConfig(
service_name="production-service",
logging=LoggingConfig(
default_level="INFO", # Don't spam with DEBUG
console_formatter="json", # Machine-readable
enabled_semantic_layers=["http"], # Enable HTTP layer for request logging
module_levels={
"security": "DEBUG", # Always verbose for security
"performance": "WARNING", # Only perf issues
"third_party": "ERROR", # Minimal external noise
}
)
)
```
## 📚 Documentation
For comprehensive API documentation, configuration options, and advanced usage patterns, see:
**[📖 Complete API Reference](docs/api-reference.md)**
## 📜 License
This project is licensed under the **Apache 2.0 License**. See the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgements
`pyvider.telemetry` builds upon these excellent open-source libraries:
- [`structlog`](https://www.structlog.org/) - The foundation for structured logging
- [`attrs`](https://www.attrs.org/) - Powerful data classes and configuration management
## 🤖 Development Transparency
**AI-Assisted Development Notice**: This project was developed with significant AI assistance for code generation and implementation. While AI tools performed much of the heavy lifting for writing code, documentation, and tests, all architectural decisions, design patterns, functionality requirements, and final verification were made by human developers.
**Human Oversight Includes**:
- Architectural design and module structure decisions
- API design and interface specifications
- Feature requirements and acceptance criteria
- Code review and functionality verification
- Performance requirements and benchmarking validation
- Testing strategy and coverage requirements
- Release readiness assessment
**AI Assistance Includes**:
- Code implementation based on human specifications
- Documentation generation and formatting
- Test case generation and implementation
- Example script creation
- Boilerplate and repetitive code generation
This approach allows us to leverage AI capabilities for productivity while maintaining human control over critical technical decisions and quality assurance.
Raw data
{
"_id": null,
"home_page": null,
"name": "pyvider-telemetry",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "\"provide.io\" <code@provide.io>",
"keywords": "telemetry, logging, tracing, python, pyvider",
"author": null,
"author_email": "Tim Perkins <code@tim.life>",
"download_url": "https://files.pythonhosted.org/packages/a8/72/037f2746257010650797a929e019b47cf53fe075b027618e50be9e43213c/pyvider_telemetry-0.0.16.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# \ud83d\udc0d\ud83d\udce1 `pyvider.telemetry`\n\n**Beautiful, performant, structured logging for Python.**\n\nModern structured logging built on `structlog` with emoji-enhanced visual parsing and semantic Domain-Action-Status patterns.\n\n[](https://github.com/astral-sh/uv)\n[](https://pypi.org/project/pyvider-telemetry/)\n[](https://pypi.org/project/pyvider-telemetry/)\n[](https://pepy.tech/project/pyvider-telemetry)\n\n[](https://github.com/provide-io/pyvider-telemetry/actions/workflows/ci.yml)\n[](https://codecov.io/gh/provide-io/pyvider-telemetry)\n[](https://mypy.readthedocs.io/)\n[](https://github.com/astral-sh/ruff)\n\n<!-- Dependencies & Performance -->\n[](https://www.structlog.org/)\n[](https://www.attrs.org/)\n[](README.md#performance)\n\n[](https://opensource.org/license/apache-2-0)\n\n---\n\n**Make your logs beautiful and meaningful!** `pyvider.telemetry` transforms your application logging with visual emoji prefixes, semantic Domain-Action-Status patterns, and high-performance structured output. Perfect for development debugging, production monitoring, and everything in between.\n\n</div>\n\n## \ud83e\udd14 Why `pyvider.telemetry`?\n\n* **\ud83c\udfa8 Visual Log Parsing:** Emoji prefixes based on logger names and semantic context make logs instantly scannable\n* **\ud83d\udcca Semantic Structure:** **(New!)** Extensible Semantic Layers for domains like LLMs, HTTP, and Databases, with a fallback to the classic Domain-Action-Status (DAS) pattern.\n* **\u26a1 High Performance:** Benchmarked >14,000 msg/sec (see details below)\n* **\ud83d\udd27 Zero Configuration:** Works beautifully out of the box, configurable via environment variables or code\n* **\ud83c\udfaf Developer Experience:** Thread-safe, async-ready, with comprehensive type hints for Python 3.13+\n\n## \u2728 Features\n\n* **\ud83c\udfa8 Emoji-Enhanced Logging:**\n * **Logger Name Prefixes:** `\ud83d\udd11 User authentication successful` (auth module)\n * **(New!) Semantic Layer Prefixes:** `[\ud83e\udd16][\u270d\ufe0f][\ud83d\udc4d] LLM response generated` (llm-generation-success)\n * **Custom TRACE Level:** Ultra-verbose debugging with `\ud83d\udc63` visual markers\n\n* **\ud83d\udcc8 Production Ready:**\n * **High Performance:** >14,000 messages/second throughput (average ~40,000 msg/sec)\n * **Thread Safe:** Concurrent logging from multiple threads\n * **Async Support:** Native async/await compatibility\n * **Memory Efficient:** Optimized emoji caching and processor chains\n\n* **\u2699\ufe0f Flexible Configuration:**\n * **Multiple Formats:** JSON for production, key-value for development\n * **Module-Level Filtering:** Different log levels per component\n * **Environment Variables:** Zero-code configuration options\n * **Service Identification:** Automatic service name injection\n\n* **\ud83c\udfd7\ufe0f Modern Python:**\n * **Python 3.13+ Exclusive:** Latest language features and typing\n * **Built with `attrs`:** Immutable, validated configuration objects\n * **Structlog Foundation:** Industry-standard structured logging\n\n## \ud83d\ude80 Installation\n\nRequires Python 3.13 or later.\n\n```bash\npip install pyvider-telemetry\n```\n\n## \ud83d\udca1 Quick Start\n\n### Basic Usage\n\n```python\nfrom pyvider.telemetry import setup_telemetry, logger\n\n# Initialize with sensible defaults\nsetup_telemetry()\n\n# Start logging immediately\nlogger.info(\"Application started\", version=\"1.0.0\")\nlogger.debug(\"Debug information\", component=\"auth\")\nlogger.error(\"Something went wrong\", error_code=\"E123\")\n\n# Create component-specific loggers\nauth_logger = logger.get_logger(\"auth.service\")\nauth_logger.info(\"User login attempt\", user_id=12345)\n# Output: \ud83d\udd11 User login attempt user_id=12345\n```\n\n### \ud83c\udfd7\ufe0f Semantic Logging with Layers\n\nGo beyond the basic DAS pattern with extensible, schema-driven logging. Semantic Layers allow you to define structured logging conventions for specific domains (like LLMs, HTTP, or Databases) and automatically get rich, contextual emoji prefixes.\n\n**Example: Using the built-in `llm` layer**\n\nFirst, enable the layer in your configuration:\n```python\nfrom pyvider.telemetry import setup_telemetry, TelemetryConfig, LoggingConfig\n\n# Enable the 'llm' semantic layer\nconfig = TelemetryConfig(\n logging=LoggingConfig(enabled_semantic_layers=[\"llm\"])\n)\nsetup_telemetry(config)\n```\n\nNow, log events using the layer's defined keys (like `llm.provider`, `llm.task`, `llm.outcome`):\n```python\nfrom pyvider.telemetry import logger\n\n# Log a successful LLM generation task\nlogger.info(\n \"LLM response generated\",\n **{\n \"llm.provider\": \"openai\",\n \"llm.task\": \"generation\",\n \"llm.outcome\": \"success\",\n \"llm.model\": \"gpt-4o\",\n \"duration_ms\": 1230,\n \"llm.output.tokens\": 250,\n }\n)\n# Output: [\ud83e\udd16][\u270d\ufe0f][\ud83d\udc4d] LLM response generated duration_ms=1230 llm.output.tokens=250\n\n# Log a rate-limiting event from another provider\nlogger.warning(\n \"LLM call failed\",\n **{\n \"llm.provider\": \"anthropic\",\n \"llm.task\": \"chat\",\n \"llm.outcome\": \"rate_limit\",\n \"llm.model\": \"claude-3-opus\",\n }\n)\n# Output: [\ud83d\udcda][\ud83d\udcac][\u23f3] LLM call failed\n```\n- **How it works:** The `llm` layer maps the `llm.provider` key to provider emojis (\ud83e\udd16 for openai, \ud83d\udcda for anthropic), `llm.task` to task emojis (\u270d\ufe0f for generation), and `llm.outcome` to outcome emojis (\ud83d\udc4d for success).\n- **Extensible:** You can define your own custom layers and emoji sets for your application's specific domains!\n- **Legacy DAS:** The original `domain`, `action`, `status` keys still work as a fallback if no semantic layers are active.\n\n### Custom Configuration\n\n```python\nfrom pyvider.telemetry import setup_telemetry, TelemetryConfig, LoggingConfig\n\nconfig = TelemetryConfig(\n service_name=\"my-microservice\",\n logging=LoggingConfig(\n default_level=\"INFO\",\n console_formatter=\"json\", # JSON for production\n # Enable built-in layers for HTTP and Database logging\n enabled_semantic_layers=[\"http\", \"database\"],\n module_levels={\n \"auth\": \"DEBUG\", # Verbose auth logging\n \"database\": \"ERROR\", # Only DB errors\n \"external.api\": \"WARNING\", # Minimal third-party noise\n }\n )\n)\n\nsetup_telemetry(config)\n```\n\n### Environment Variable Configuration\n\n```bash\nexport PYVIDER_SERVICE_NAME=\"my-service\"\nexport PYVIDER_LOG_LEVEL=\"INFO\"\nexport PYVIDER_LOG_CONSOLE_FORMATTER=\"json\"\nexport PYVIDER_LOG_MODULE_LEVELS=\"auth:DEBUG,db:ERROR\"\n# New: Enable semantic layers via environment\nexport PYVIDER_LOG_ENABLED_SEMANTIC_LAYERS=\"llm,http\"\n```\n\n```python\nfrom pyvider.telemetry import setup_telemetry, TelemetryConfig\n\n# Automatically loads from environment\nsetup_telemetry(TelemetryConfig.from_env())\n```\n\n### Exception Logging\n\n```python\ntry:\n risky_operation()\nexcept Exception:\n logger.exception(\"Operation failed\",\n operation=\"user_registration\",\n user_id=123)\n # Automatically includes full traceback\n```\n\n### Ultra-Verbose TRACE Logging\n\n```python\nfrom pyvider.telemetry import setup_telemetry, logger, TelemetryConfig, LoggingConfig\n\n# Enable TRACE level for deep debugging\nconfig = TelemetryConfig(\n logging=LoggingConfig(default_level=\"TRACE\")\n)\nsetup_telemetry(config)\n\nlogger.trace(\"Entering function\", function=\"authenticate_user\")\nlogger.trace(\"Token validation details\",\n token_type=\"bearer\", expires_in=3600)\n```\n\n## \ud83d\udcca Performance\n\n`pyvider.telemetry` is designed for high-throughput production environments:\n\n| Scenario | Performance | Notes |\n|----------|-------------|-------|\n| **Basic Logging** | ~40,000 msg/sec | Key-value format with emojis |\n| **JSON Output** | ~38,900 msg/sec | Structured production format |\n| **Multithreaded** | ~39,800 msg/sec | Concurrent logging |\n| **Level Filtering** | ~68,100 msg/sec | Efficiently filters by level |\n| **Large Payloads** | ~14,200 msg/sec | Logging with larger event data |\n| **Async Logging** | ~43,400 msg/sec | Logging from async code |\n\n**Overall Average Throughput:** ~40,800 msg/sec\n**Peak Throughput:** ~68,100 msg/sec\n\nRun benchmarks yourself:\n```bash\npython scripts/benchmark_performance.py\n\npython scripts/extreme_performance.py\n```\n\n## \ud83c\udfa8 Emoji Reference\n\nThe emoji system is now driven by **Semantic Layers**. The active layers determine which log keys produce emoji prefixes.\n\n### Viewing the Active Emoji Contract\n\nTo see the complete emoji mappings for your **current configuration** (including any custom layers), run the following command. This is the best way to see which emojis are active.\n\n```bash\n# This will print the full emoji matrix for your active configuration\nexport PYVIDER_SHOW_EMOJI_MATRIX=true\npython -c \"from pyvider.telemetry.logger.emoji_matrix import show_emoji_matrix; show_emoji_matrix()\"\n```\n\n### Built-in Layer Emojis (Examples)\n\n- **`llm` Layer:**\n - **Provider:** `llm.provider` -> `\ud83e\udd16` (openai), `\ud83d\udcda` (anthropic), `\ud83e\udd99` (meta)\n - **Task:** `llm.task` -> `\u270d\ufe0f` (generation), `\ud83d\udcac` (chat), `\ud83d\udee0\ufe0f` (tool_use)\n - **Outcome:** `llm.outcome` -> `\ud83d\udc4d` (success), `\ud83d\udd25` (error), `\u23f3` (rate_limit)\n\n- **`http` Layer:**\n - **Method:** `http.method` -> `\ud83d\udce5` (get), `\ud83d\udce4` (post), `\ud83d\uddd1\ufe0f` (delete)\n - **Status Class:** `http.status_class` -> `\u2705` (2xx), `\u26a0\ufe0fCLIENT` (4xx), `\ud83d\udd25SERVER` (5xx)\n\n### Legacy DAS Emojis (Fallback)\n\nThese emojis are used when no semantic layers are active and you use the `domain`, `action`, and `status` keys.\n\n- **Domain Emojis (Primary):** `\ud83d\udd11` auth, `\ud83d\uddc4\ufe0f` database, `\ud83c\udf10` network, `\u2699\ufe0f` system\n- **Action Emojis (Secondary):** `\u27a1\ufe0f` login, `\ud83d\udd17` connect, `\ud83d\udce4` send, `\ud83d\udd0d` query\n- **Status Emojis (Tertiary):** `\u2705` success, `\ud83d\udd25` error, `\u26a0\ufe0f` warning, `\u23f3` attempt\n\n\n## \ud83d\udd27 Advanced Usage\n\n### Async Applications\n\n```python\nimport asyncio\nfrom pyvider.telemetry import setup_telemetry, logger, shutdown_pyvider_telemetry\n\nasync def main():\n setup_telemetry()\n\n # Your async application code\n logger.info(\"Async app started\")\n\n # Graceful shutdown\n await shutdown_pyvider_telemetry()\n\nasyncio.run(main())\n```\n\n<!-- NEW SECTION -->\n### Timing Code Blocks\n\nEasily log the duration and outcome of any code block using the `timed_block` context manager. It automatically handles success and failure cases.\n\n```python\nimport time\nfrom pyvider.telemetry import logger, timed_block\n\n# Successful operation\nwith timed_block(logger, \"Data processing task\", task_id=\"abc-123\"):\n time.sleep(0.05) # Simulate work\n# Output: Data processing task task_id=abc-123 outcome=success duration_ms=50\n\n# Failing operation\ntry:\n with timed_block(logger, \"Database query\", table=\"users\"):\n raise ValueError(\"Connection refused\")\nexcept ValueError:\n pass # Exception is re-raised and caught here\n# Output: Database query table=users outcome=error error.message='Connection refused' error.type=ValueError duration_ms=...\n```\n<!-- END NEW SECTION -->\n\n### Production Configuration\n\n```python\nproduction_config = TelemetryConfig(\n service_name=\"production-service\",\n logging=LoggingConfig(\n default_level=\"INFO\", # Don't spam with DEBUG\n console_formatter=\"json\", # Machine-readable\n enabled_semantic_layers=[\"http\"], # Enable HTTP layer for request logging\n module_levels={\n \"security\": \"DEBUG\", # Always verbose for security\n \"performance\": \"WARNING\", # Only perf issues\n \"third_party\": \"ERROR\", # Minimal external noise\n }\n )\n)\n```\n\n## \ud83d\udcda Documentation\n\nFor comprehensive API documentation, configuration options, and advanced usage patterns, see:\n\n**[\ud83d\udcd6 Complete API Reference](docs/api-reference.md)**\n\n## \ud83d\udcdc License\n\nThis project is licensed under the **Apache 2.0 License**. See the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgements\n\n`pyvider.telemetry` builds upon these excellent open-source libraries:\n\n- [`structlog`](https://www.structlog.org/) - The foundation for structured logging\n- [`attrs`](https://www.attrs.org/) - Powerful data classes and configuration management\n\n## \ud83e\udd16 Development Transparency\n\n**AI-Assisted Development Notice**: This project was developed with significant AI assistance for code generation and implementation. While AI tools performed much of the heavy lifting for writing code, documentation, and tests, all architectural decisions, design patterns, functionality requirements, and final verification were made by human developers.\n\n**Human Oversight Includes**:\n- Architectural design and module structure decisions\n- API design and interface specifications \n- Feature requirements and acceptance criteria\n- Code review and functionality verification\n- Performance requirements and benchmarking validation\n- Testing strategy and coverage requirements\n- Release readiness assessment\n\n**AI Assistance Includes**:\n- Code implementation based on human specifications\n- Documentation generation and formatting\n- Test case generation and implementation\n- Example script creation\n- Boilerplate and repetitive code generation\n\nThis approach allows us to leverage AI capabilities for productivity while maintaining human control over critical technical decisions and quality assurance.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Pyvider Telemetry: An opinionated, developer-friendly telemetry wrapper for Python.",
"version": "0.0.16",
"project_urls": {
"Homepage": "https://pyvider.com/",
"Repository": "https://github.com/provider-io/pyvider-telemetry"
},
"split_keywords": [
"telemetry",
" logging",
" tracing",
" python",
" pyvider"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "48e5fe68ec31bff7628b9c73a3c3588e5cbb04dc540941fe7bb0e64408c17945",
"md5": "3e82653af0c7adac55abbf817584bb5e",
"sha256": "13f550eb19b5ad50af705856cfcb6c946ccf72d3263fcbb7087ad48224d87145"
},
"downloads": -1,
"filename": "pyvider_telemetry-0.0.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e82653af0c7adac55abbf817584bb5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 33497,
"upload_time": "2025-08-20T04:06:24",
"upload_time_iso_8601": "2025-08-20T04:06:24.866363Z",
"url": "https://files.pythonhosted.org/packages/48/e5/fe68ec31bff7628b9c73a3c3588e5cbb04dc540941fe7bb0e64408c17945/pyvider_telemetry-0.0.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a872037f2746257010650797a929e019b47cf53fe075b027618e50be9e43213c",
"md5": "ae78c193a11a57983e4aff280aa87c11",
"sha256": "0897cc0de49ab52538ccccb2e0013cfcc64783045de038d2c6110c4f1b450b6d"
},
"downloads": -1,
"filename": "pyvider_telemetry-0.0.16.tar.gz",
"has_sig": false,
"md5_digest": "ae78c193a11a57983e4aff280aa87c11",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 79743,
"upload_time": "2025-08-20T04:06:25",
"upload_time_iso_8601": "2025-08-20T04:06:25.881360Z",
"url": "https://files.pythonhosted.org/packages/a8/72/037f2746257010650797a929e019b47cf53fe075b027618e50be9e43213c/pyvider_telemetry-0.0.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 04:06:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "provider-io",
"github_project": "pyvider-telemetry",
"github_not_found": true,
"lcname": "pyvider-telemetry"
}
JSON
