# Artissist Logger - Python Client
Platform-agnostic logging client for the Artissist platform.
## Features
- 🎯 **Pre-defined Events**: 25 built-in event types with emoji support
- 🎨 **Emoji Integration**: Configurable emoji prefixes for visual log scanning
- 📊 **Structured Logging**: Rich metadata, metrics, and error information
- 🔄 **Context Management**: Distributed tracing with correlation IDs
- 🔌 **Adapter Pattern**: Multiple output destinations (console, file, cloud)
- 🏭 **Factory Pattern**: Specialized loggers for different components
- ⚡ **Async Support**: Non-blocking logging with async/await
- 🛡️ **Type Safety**: Full type hints and runtime validation
## Installation
```bash
pip install artissist-logger
```
### Development Installation
```bash
pip install -e .[dev]
```
## Quick Start
```python
from artissist_logger import LoggerFactory, LogEvent
# Create a backend logger
logger = LoggerFactory.create_backend_logger(
service="my-service",
environment="development",
emojis=True # Enable emojis for development
)
# Basic logging
await logger.info("Service starting up", event=LogEvent.SYSTEM_START)
await logger.error("Database connection failed", event=LogEvent.ERROR_OCCURRED)
# With structured data
await logger.info(
"User authenticated successfully",
event=LogEvent.USER_AUTH,
metadata={"user_id": "user_123", "method": "oauth"},
metrics={"auth_duration_ms": 150}
)
```
The Logger exposes convenience methods for each level (`debug`, `info`, `warn`, `error`, etc.). Use `logger.log(level, message, **kwargs)` only when the level must be chosen dynamically.
## Logger Types
### Backend Logger
```python
logger = LoggerFactory.create_backend_logger(
service="api-server",
environment="production",
emojis=False # Disabled for production
)
```
### Agent Logger
```python
logger = LoggerFactory.create_agent_logger(
agent_id="conv_001",
agent_type="conversation",
environment="development",
emojis=True
)
```
### Infrastructure Logger
```python
logger = LoggerFactory.create_infrastructure_logger(
component="deployment-manager",
environment="production"
)
```
## Context Management
### Global Context
```python
from artissist_logger import ContextManager, LoggerContext
# Set global context
ContextManager.set_context(LoggerContext(
correlation_id="req_123",
user_id="user_456"
))
# All subsequent logs will include this context
await logger.info("Processing request") # Includes correlation_id and user_id
```
### Scoped Context
```python
# Temporary context for a specific operation
with ContextManager.context(user_id="user_789", operation="data_export"):
await logger.info("Starting export") # Includes user_id and operation
await logger.info("Export completed")
```
### Logger Context
```python
# Create logger with permanent context
contextual_logger = logger.with_context(
service_version="1.2.0",
deployment_id="deploy_abc"
)
await contextual_logger.info("Service initialized") # Includes service_version and deployment_id
```
## Events and Emojis
### Pre-defined Events
```python
# System events
LogEvent.SYSTEM_START # 🚀 System startup
LogEvent.ERROR_OCCURRED # 🐛 Errors and exceptions
LogEvent.WARNING_ISSUED # ⚠️ Warning conditions
# Business events
LogEvent.USER_AUTH # 👤 User authentication
LogEvent.PROJECT_LIFECYCLE # 📁 Project management
LogEvent.AI_INFERENCE # 🧠 AI model operations
# Technical events
LogEvent.API_REQUEST # 🔄 API calls
LogEvent.DATABASE_OPERATION # 💾 Database queries
LogEvent.PERFORMANCE_METRIC # ⚡ Performance measurements
```
### Custom Events
```python
from artissist_logger import EmojiResolver, EmojiMapping
# Create custom emoji mappings
resolver = EmojiResolver()
resolver.add_custom_mapping("payment_processed", EmojiMapping(
emoji="💳",
description="Payment processing events"
))
logger = LoggerFactory.create_logger(
service="payment-service",
environment="development",
adapters=["console"],
emojis=True,
emoji_resolver=resolver
)
# Use custom event
await logger.info("Payment completed", custom_event="payment_processed")
# Output: 💳 Payment completed
```
## Error Handling
```python
from artissist_logger import ErrorInfo
try:
# Some operation that might fail
process_data()
except Exception as e:
await logger.error(
"Data processing failed",
event=LogEvent.ERROR_OCCURRED,
error=ErrorInfo(
type=type(e).__name__,
message=str(e),
stack_trace=traceback.format_exc(),
context={"batch_id": "batch_123"}
)
)
```
## Metrics
```python
from artissist_logger import LogMetrics
# Performance metrics
await logger.info(
"Database query completed",
event=LogEvent.DATABASE_OPERATION,
metrics=LogMetrics(
duration_ms=45.2,
count=150,
bytes_processed=1024000
)
)
# Business metrics
await logger.info(
"User signup completed",
event=LogEvent.BUSINESS_METRIC,
metadata={"user_type": "premium"},
metrics=LogMetrics(
count=1,
custom_metrics={"revenue_impact": 29.99}
)
)
```
## Adapters
### Console Adapter
```python
# Development console output with colors
LoggerFactory.create_logger(
service="my-service",
environment="development",
adapters=["console"],
adapter_configs={
"console": {"colors": True, "use_stderr": False}
}
)
```
### File Adapter
```python
# Production file logging with rotation
LoggerFactory.create_logger(
service="my-service",
environment="production",
adapters=["file"],
adapter_configs={
"file": {
"file_path": "logs/service.log",
"format": "json",
"rotate": True,
"max_size_mb": 50,
"max_files": 10
}
}
)
```
### Multiple Adapters
```python
# Both console and file output
LoggerFactory.create_backend_logger(
service="api-service",
environment="production",
adapters=["console", "file"]
)
```
## Synchronous Usage
For non-async contexts:
```python
# Synchronous convenience methods (fire-and-forget)
logger.info_sync("Service started", event=LogEvent.SYSTEM_START)
logger.error_sync("Connection failed", event=LogEvent.ERROR_OCCURRED)
```
## Configuration
### Environment Variables
```bash
export ARTISSIST_LOG_LEVEL=INFO
export ARTISSIST_LOG_EMOJIS=true
export ARTISSIST_LOG_FORMAT=json
```
### Programmatic Configuration
```python
config = {
"service": "my-service",
"environment": "production",
"adapters": ["console", "file"],
"emojis": False,
"adapter_configs": {
"console": {"colors": False},
"file": {"file_path": "/var/log/my-service.log"}
}
}
logger = LoggerFactory.create_logger(**config)
```
## Development
### Running Tests
```bash
pytest
pytest --cov=artissist_logger # With coverage
```
### Code Formatting
```bash
black artissist_logger/
mypy artissist_logger/
flake8 artissist_logger/
```
### Build Package
```bash
python setup.py bdist_wheel
```
## Integration Examples
See the `examples/` directory for complete integration examples:
- FastAPI backend service
- Agent processing systems
- Infrastructure deployment logging
- Error handling patterns
- Performance monitoring
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/artissist/logger",
"name": "artissist-logger",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "logging, observability, telemetry, platform, artissist",
"author": "Artissist",
"author_email": "dev@artissist.com",
"download_url": "https://files.pythonhosted.org/packages/52/07/8d7025f8603116c3fc55ac9cbfdef1780aeb1dceaa3ceb4572d9fdf642ca/artissist_logger-0.1.1.tar.gz",
"platform": null,
"description": "# Artissist Logger - Python Client\n\nPlatform-agnostic logging client for the Artissist platform.\n\n## Features\n\n- \ud83c\udfaf **Pre-defined Events**: 25 built-in event types with emoji support\n- \ud83c\udfa8 **Emoji Integration**: Configurable emoji prefixes for visual log scanning\n- \ud83d\udcca **Structured Logging**: Rich metadata, metrics, and error information\n- \ud83d\udd04 **Context Management**: Distributed tracing with correlation IDs\n- \ud83d\udd0c **Adapter Pattern**: Multiple output destinations (console, file, cloud)\n- \ud83c\udfed **Factory Pattern**: Specialized loggers for different components\n- \u26a1 **Async Support**: Non-blocking logging with async/await\n- \ud83d\udee1\ufe0f **Type Safety**: Full type hints and runtime validation\n\n## Installation\n\n```bash\npip install artissist-logger\n```\n\n### Development Installation\n\n```bash\npip install -e .[dev]\n```\n\n## Quick Start\n\n```python\nfrom artissist_logger import LoggerFactory, LogEvent\n\n# Create a backend logger\nlogger = LoggerFactory.create_backend_logger(\n service=\"my-service\",\n environment=\"development\", \n emojis=True # Enable emojis for development\n)\n\n# Basic logging\nawait logger.info(\"Service starting up\", event=LogEvent.SYSTEM_START)\nawait logger.error(\"Database connection failed\", event=LogEvent.ERROR_OCCURRED)\n\n# With structured data\nawait logger.info(\n \"User authenticated successfully\",\n event=LogEvent.USER_AUTH,\n metadata={\"user_id\": \"user_123\", \"method\": \"oauth\"},\n metrics={\"auth_duration_ms\": 150}\n)\n```\n\nThe Logger exposes convenience methods for each level (`debug`, `info`, `warn`, `error`, etc.). Use `logger.log(level, message, **kwargs)` only when the level must be chosen dynamically.\n\n## Logger Types\n\n### Backend Logger\n```python\nlogger = LoggerFactory.create_backend_logger(\n service=\"api-server\",\n environment=\"production\",\n emojis=False # Disabled for production\n)\n```\n\n### Agent Logger \n```python\nlogger = LoggerFactory.create_agent_logger(\n agent_id=\"conv_001\",\n agent_type=\"conversation\",\n environment=\"development\",\n emojis=True\n)\n```\n\n### Infrastructure Logger\n```python\nlogger = LoggerFactory.create_infrastructure_logger(\n component=\"deployment-manager\", \n environment=\"production\"\n)\n```\n\n## Context Management\n\n### Global Context\n```python\nfrom artissist_logger import ContextManager, LoggerContext\n\n# Set global context\nContextManager.set_context(LoggerContext(\n correlation_id=\"req_123\",\n user_id=\"user_456\"\n))\n\n# All subsequent logs will include this context\nawait logger.info(\"Processing request\") # Includes correlation_id and user_id\n```\n\n### Scoped Context\n```python\n# Temporary context for a specific operation\nwith ContextManager.context(user_id=\"user_789\", operation=\"data_export\"):\n await logger.info(\"Starting export\") # Includes user_id and operation\n await logger.info(\"Export completed\")\n```\n\n### Logger Context\n```python\n# Create logger with permanent context\ncontextual_logger = logger.with_context(\n service_version=\"1.2.0\",\n deployment_id=\"deploy_abc\"\n)\n\nawait contextual_logger.info(\"Service initialized\") # Includes service_version and deployment_id\n```\n\n## Events and Emojis\n\n### Pre-defined Events\n```python\n# System events\nLogEvent.SYSTEM_START # \ud83d\ude80 System startup\nLogEvent.ERROR_OCCURRED # \ud83d\udc1b Errors and exceptions\nLogEvent.WARNING_ISSUED # \u26a0\ufe0f Warning conditions\n\n# Business events \nLogEvent.USER_AUTH # \ud83d\udc64 User authentication\nLogEvent.PROJECT_LIFECYCLE # \ud83d\udcc1 Project management\nLogEvent.AI_INFERENCE # \ud83e\udde0 AI model operations\n\n# Technical events\nLogEvent.API_REQUEST # \ud83d\udd04 API calls\nLogEvent.DATABASE_OPERATION # \ud83d\udcbe Database queries\nLogEvent.PERFORMANCE_METRIC # \u26a1 Performance measurements\n```\n\n### Custom Events\n```python\nfrom artissist_logger import EmojiResolver, EmojiMapping\n\n# Create custom emoji mappings\nresolver = EmojiResolver()\nresolver.add_custom_mapping(\"payment_processed\", EmojiMapping(\n emoji=\"\ud83d\udcb3\", \n description=\"Payment processing events\"\n))\n\nlogger = LoggerFactory.create_logger(\n service=\"payment-service\",\n environment=\"development\", \n adapters=[\"console\"],\n emojis=True,\n emoji_resolver=resolver\n)\n\n# Use custom event\nawait logger.info(\"Payment completed\", custom_event=\"payment_processed\")\n# Output: \ud83d\udcb3 Payment completed\n```\n\n## Error Handling\n\n```python\nfrom artissist_logger import ErrorInfo\n\ntry:\n # Some operation that might fail\n process_data()\nexcept Exception as e:\n await logger.error(\n \"Data processing failed\",\n event=LogEvent.ERROR_OCCURRED,\n error=ErrorInfo(\n type=type(e).__name__,\n message=str(e),\n stack_trace=traceback.format_exc(),\n context={\"batch_id\": \"batch_123\"}\n )\n )\n```\n\n## Metrics\n\n```python\nfrom artissist_logger import LogMetrics\n\n# Performance metrics\nawait logger.info(\n \"Database query completed\",\n event=LogEvent.DATABASE_OPERATION,\n metrics=LogMetrics(\n duration_ms=45.2,\n count=150,\n bytes_processed=1024000\n )\n)\n\n# Business metrics\nawait logger.info(\n \"User signup completed\", \n event=LogEvent.BUSINESS_METRIC,\n metadata={\"user_type\": \"premium\"},\n metrics=LogMetrics(\n count=1,\n custom_metrics={\"revenue_impact\": 29.99}\n )\n)\n```\n\n## Adapters\n\n### Console Adapter\n```python\n# Development console output with colors\nLoggerFactory.create_logger(\n service=\"my-service\",\n environment=\"development\",\n adapters=[\"console\"],\n adapter_configs={\n \"console\": {\"colors\": True, \"use_stderr\": False}\n }\n)\n```\n\n### File Adapter\n```python\n# Production file logging with rotation\nLoggerFactory.create_logger(\n service=\"my-service\", \n environment=\"production\",\n adapters=[\"file\"],\n adapter_configs={\n \"file\": {\n \"file_path\": \"logs/service.log\",\n \"format\": \"json\",\n \"rotate\": True,\n \"max_size_mb\": 50,\n \"max_files\": 10\n }\n }\n)\n```\n\n### Multiple Adapters\n```python\n# Both console and file output\nLoggerFactory.create_backend_logger(\n service=\"api-service\",\n environment=\"production\",\n adapters=[\"console\", \"file\"]\n)\n```\n\n## Synchronous Usage\n\nFor non-async contexts:\n\n```python\n# Synchronous convenience methods (fire-and-forget)\nlogger.info_sync(\"Service started\", event=LogEvent.SYSTEM_START)\nlogger.error_sync(\"Connection failed\", event=LogEvent.ERROR_OCCURRED)\n```\n\n## Configuration\n\n### Environment Variables\n```bash\nexport ARTISSIST_LOG_LEVEL=INFO\nexport ARTISSIST_LOG_EMOJIS=true\nexport ARTISSIST_LOG_FORMAT=json\n```\n\n### Programmatic Configuration\n```python\nconfig = {\n \"service\": \"my-service\",\n \"environment\": \"production\",\n \"adapters\": [\"console\", \"file\"],\n \"emojis\": False,\n \"adapter_configs\": {\n \"console\": {\"colors\": False},\n \"file\": {\"file_path\": \"/var/log/my-service.log\"}\n }\n}\n\nlogger = LoggerFactory.create_logger(**config)\n```\n\n## Development\n\n### Running Tests\n```bash\npytest\npytest --cov=artissist_logger # With coverage\n```\n\n### Code Formatting\n```bash\nblack artissist_logger/\nmypy artissist_logger/\nflake8 artissist_logger/\n```\n\n### Build Package\n```bash\npython setup.py bdist_wheel\n```\n\n## Integration Examples\n\nSee the `examples/` directory for complete integration examples:\n- FastAPI backend service\n- Agent processing systems \n- Infrastructure deployment logging\n- Error handling patterns\n- Performance monitoring\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Platform-agnostic logging client for Artissist",
"version": "0.1.1",
"project_urls": {
"Bug Reports": "https://github.com/artissist/logger/issues",
"Documentation": "https://github.com/artissist/logger",
"Homepage": "https://github.com/artissist/logger",
"Source": "https://github.com/artissist/logger"
},
"split_keywords": [
"logging",
" observability",
" telemetry",
" platform",
" artissist"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5a9ca35933b2c2062c45b7857d2900bbca075b805d6011e3d8de84097e309881",
"md5": "0e237363e1263557b074b81f6e7d985d",
"sha256": "9221218a9e35f489fc029592c56e338a4a1e3eda132a6fe93a7439ccee00cdd7"
},
"downloads": -1,
"filename": "artissist_logger-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e237363e1263557b074b81f6e7d985d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16859,
"upload_time": "2025-09-12T12:16:20",
"upload_time_iso_8601": "2025-09-12T12:16:20.745526Z",
"url": "https://files.pythonhosted.org/packages/5a/9c/a35933b2c2062c45b7857d2900bbca075b805d6011e3d8de84097e309881/artissist_logger-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "52078d7025f8603116c3fc55ac9cbfdef1780aeb1dceaa3ceb4572d9fdf642ca",
"md5": "5eaa0aedce95ab4779cb5c903967c015",
"sha256": "8f6a7612ca6c22acdadf276f28aa4cd8731399a9d63ac42bfbea61664ef00448"
},
"downloads": -1,
"filename": "artissist_logger-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "5eaa0aedce95ab4779cb5c903967c015",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16763,
"upload_time": "2025-09-12T12:16:21",
"upload_time_iso_8601": "2025-09-12T12:16:21.860670Z",
"url": "https://files.pythonhosted.org/packages/52/07/8d7025f8603116c3fc55ac9cbfdef1780aeb1dceaa3ceb4572d9fdf642ca/artissist_logger-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 12:16:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "artissist",
"github_project": "logger",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "artissist-logger"
}
JSON
