# PyLogHub/Loggier Documentation
## Overview
PyLogHub (Loggier) is a comprehensive logging solution for Python applications, with specialized integrations for web frameworks like Django, Flask, and FastAPI. It offers a flexible and powerful way to collect, process, and analyze logs from your applications with features like asynchronous logging, local caching, performance monitoring, and web framework integrations.
## Table of Contents
1. [Installation](#installation)
2. [Core Concepts](#core-concepts)
3. [Basic Usage](#basic-usage)
4. [Advanced Configuration](#advanced-configuration)
5. [Django Integration](#django-integration)
6. [Flask Integration](#flask-integration)
7. [FastAPI Integration](#fastapi-integration)
8. [Performance Monitoring](#performance-monitoring)
9. [Error Tracking](#error-tracking)
10. [Architecture](#architecture)
11. [API Reference](#api-reference)
## Installation
Install using pip:
```bash
pip install loggier
```
## Core Concepts
PyLogHub/Loggier is built around these core concepts:
- **Client**: The main Loggier class that handles log collection and sending
- **Handlers**: Components that process and deliver logs (API, Async, Cache)
- **Formatters**: Components that format logs for output
- **Context**: A system for adding and organizing contextual information
- **Integrations**: Framework-specific components for seamless integration
## Basic Usage
Simple example of using Loggier:
```python
from loggier import Loggier
# Create a Loggier instance
logger = Loggier(
api_key="your-api-key",
environment="development",
service_name="my-service"
)
# Log basic messages
logger.info("Application started")
logger.warning("Something might be wrong", context={"user_id": 123})
logger.error("Something went wrong", context={"order_id": "ORD-123456"})
# Log exceptions
try:
# Some code that might raise an exception
result = 1 / 0
except Exception as e:
logger.exception("Error calculating result", exception=e)
# Use context for adding structured information
with logger.context(user_id=123, transaction_id="TX12345"):
logger.info("Processing transaction")
try:
# Transaction processing code
logger.info("Transaction completed")
except Exception as e:
logger.exception("Transaction failed", exception=e)
# Make sure to flush logs before application exits
logger.flush()
```
## Advanced Configuration
Loggier provides many configuration options:
```python
from loggier import Loggier
logger = Loggier(
api_key="your-api-key",
project_name="my-project",
environment="production",
service_name="payment-service",
api_url="https://api.loggier.com/api/ingest", # Custom API endpoint
async_mode=True, # Send logs asynchronously
capture_uncaught=True, # Capture uncaught exceptions
log_level=logging.INFO, # Minimum log level
enable_caching=True, # Cache logs when offline
cache_dir="/path/to/cache", # Custom cache directory
max_batch_size=20, # Logs per batch
flush_interval=5, # Auto-flush interval (seconds)
sensitive_fields=["password", "credit_card"], # Fields to mask
max_retries=3, # API retry attempts
http_timeout=5, # API timeout (seconds)
network_check_interval=60, # Network check interval
tags=["api", "payments"], # Global tags
enable_performance_monitoring=True # Enable performance monitoring
)
```
## Django Integration
Loggier offers a powerful Django integration that can track requests, responses, and errors.
### Basic Setup
Add the middleware to your Django settings:
```python
# settings.py
MIDDLEWARE = [
# other middleware...
'loggier.integrations.django.LoggierDjangoMiddleware',
# other middleware...
]
# Configure Loggier
LOGGIER = {
'API_KEY': 'your-api-key-here',
'API_URL': 'https://api.loggier.com/api/ingest',
'ENVIRONMENT': 'production',
'TAGS': ['django', 'web'],
'CAPTURE_REQUEST_DATA': True,
'LOG_SLOW_REQUESTS': True,
'SLOW_REQUEST_THRESHOLD': 1.0, # seconds
'STATUSES_TO_TRACK': [500, 400, 401, 403], # Status codes to track
'CAPTURE_REQUEST_BODY': False, # Be careful with sensitive data
'CAPTURE_RESPONSE_BODY': True, # Capture response bodies for errors
'MAX_BODY_SIZE': 16384, # Max body size to capture (16KB)
'INCLUDE_STACKTRACE': True # Include stacktrace for errors
}
```
### Tracking Specific Endpoints
Use the `track_endpoint` decorator to track specific views or endpoints:
```python
from loggier.integrations.django import track_endpoint
from django.http import JsonResponse
# Track this endpoint with custom settings
@track_endpoint(
tags=['critical', 'payment'],
capture_request_body=True,
capture_response_body=True,
statuses=[200, 201, 400, 500]
)
def payment_process(request):
# This endpoint will have complete request/response tracking
return JsonResponse({"status": "success"})
```
### Django Rest Framework Integration
With Django Rest Framework, you can track specific ViewSet methods:
```python
from rest_framework import viewsets
from loggier.integrations.django import track_endpoint
class UserViewSet(viewsets.ModelViewSet):
queryset = User.objects.all()
serializer_class = UserSerializer
# Track only the list action
@track_endpoint(tags=['user', 'list'])
def list(self, request, *args, **kwargs):
return super().list(request, *args, **kwargs)
# Track the create action with body capturing
@track_endpoint(
tags=['user', 'create'],
capture_request_body=True,
capture_response_body=True
)
def create(self, request, *args, **kwargs):
return super().create(request, *args, **kwargs)
```
### Complete Transaction Tracking
The Django middleware can track the complete context of HTTP transactions:
1. **Request Information**:
- HTTP method, path, query parameters
- Headers (filtered for sensitive data)
- Request body (if enabled)
- User information
- View/controller information
2. **Response Information**:
- Status code
- Response headers
- Response time
- Response body (if enabled)
3. **Error Information**:
- Exception type and message
- Full traceback
- Application state at time of error
4. **Custom Context**:
- Add custom context using `logger.context.update_global()`
### Example Log Output (Error):
```json
{
"level": "ERROR",
"message": "Server error: GET /api/v1/templates/ - 500",
"timestamp": "2025-03-09T11:41:29.000Z",
"context": {
"request_id": "3c4e6f8g-9h0i-1j2k-3l4m-5n6o7p8q9r0s",
"transaction": {
"request": {
"method": "GET",
"path": "/api/v1/templates/",
"query_params": {
"limit": "100",
"offset": "0"
},
"user": {
"user_id": 5,
"username": "john.doe@example.com"
}
},
"response": {
"status_code": 500,
"content_type": "text/plain; charset=utf-8",
"traceback": "Traceback (most recent call last):...",
"exception": {
"type": "ValueError",
"value": "Uncaught"
}
}
}
}
}
```
## Flask Integration
Loggier provides integration with Flask:
```python
from flask import Flask
from loggier.integrations.flask import LoggierFlask
app = Flask(__name__)
# Initialize Loggier
loggier = LoggierFlask(
api_key="your-api-key",
environment="production",
capture_request_data=True,
log_slow_requests=True,
slow_request_threshold=1.0
)
# Register with Flask
loggier.init_app(app)
@app.route('/')
def index():
return "Hello World!"
if __name__ == '__main__':
app.run()
```
## FastAPI Integration
Loggier integrates with FastAPI:
```python
from fastapi import FastAPI
from loggier.integrations.fastapi import LoggierFastAPI
app = FastAPI()
# Initialize Loggier
loggier = LoggierFastAPI(
api_key="your-api-key",
environment="production",
capture_request_data=True,
log_slow_requests=True,
slow_request_threshold=1.0
)
# Register with FastAPI
loggier.init_app(app)
@app.get("/")
def read_root():
return {"Hello": "World"}
```
## Performance Monitoring
Loggier includes tools for performance monitoring:
```python
from loggier import Loggier
logger = Loggier(
api_key="your-api-key",
environment="production",
enable_performance_monitoring=True
)
# Track function performance
@logger.trace_function(threshold_ms=100)
def process_data(data):
# Function execution time will be tracked
# If it exceeds 100ms, it will be logged
return data
# Track HTTP requests
@logger.trace_http(threshold_ms=1000)
def fetch_external_api():
import requests
return requests.get("https://api.example.com/data")
# Track database operations
@logger.trace_database(threshold_ms=50)
def get_user(user_id):
# Database operation time will be tracked
return User.objects.get(id=user_id)
```
## Error Tracking
Loggier provides comprehensive error tracking capabilities:
```python
from loggier import Loggier
logger = Loggier(
api_key="your-api-key",
environment="production",
capture_uncaught=True # Automatically capture uncaught exceptions
)
# Manually log exceptions
try:
# Some code that might raise an exception
result = 1 / 0
except Exception as e:
logger.exception(
"Division error",
exception=e,
context={
"operation": "division",
"numerator": 1,
"denominator": 0
}
)
# Capture exceptions in functions
@logger.capture_exceptions
def risky_function():
# If this function raises an exception, it will be logged
return 1 / 0
```
## Architecture
PyLogHub/Loggier uses a modular architecture:
1. **Client (Loggier)**: Main interface for applications
2. **Handlers**:
- **APIHandler**: Communicates with the PyLogHub API
- **AsyncHandler**: Handles asynchronous log sending
- **CacheHandler**: Manages local caching of logs
3. **Formatters**:
- **JSONFormatter**: Formats logs as JSON
4. **Utils**:
- **Context**: Manages contextual information
- **Error**: Handles exception capturing
- **Network**: Monitors network connectivity
## API Reference
### Loggier Class
The main client class for interacting with PyLogHub.
#### Constructor
```python
Loggier(
api_key: str,
project_name: Optional[str] = None,
environment: str = "development",
api_url: Optional[str] = None,
service_name: Optional[str] = None,
async_mode: bool = True,
capture_uncaught: bool = True,
log_level: int = logging.INFO,
enable_caching: bool = True,
cache_dir: Optional[str] = None,
max_batch_size: int = 20,
flush_interval: int = 5,
sensitive_fields: Optional[List[str]] = None,
max_retries: int = 3,
http_timeout: int = 5,
network_check_interval: int = 60,
tags: Optional[List[str]] = None,
enable_performance_monitoring: bool = True
)
```
#### Logging Methods
```python
# Basic logging methods
log(level: str, message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool
debug(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool
info(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool
warning(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool
error(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool
critical(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool
exception(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool
# Context management
context(**kwargs) -> Context
# Performance monitoring decorators
trace_function(name: Optional[str] = None, threshold_ms: int = 500, tags: Optional[List[str]] = None, include_args: bool = False, include_return: bool = False, log_level: str = "INFO") -> Callable
trace_http(name: Optional[str] = None, threshold_ms: int = 1000, tags: Optional[List[str]] = None, mask_headers: Optional[List[str]] = None, mask_params: Optional[List[str]] = None, include_body: bool = False, log_level: str = "INFO") -> Callable
trace_database(name: Optional[str] = None, threshold_ms: int = 100, tags: Optional[List[str]] = None, include_params: bool = False, log_level: str = "INFO") -> Callable
# Utility methods
flush(timeout: Optional[float] = None) -> bool
get_stats() -> Dict[str, Any]
shutdown(timeout: Optional[float] = None) -> None
```
### Django Integration
#### LoggierDjangoMiddleware
```python
# In settings.py
MIDDLEWARE = [
'loggier.integrations.django.LoggierDjangoMiddleware',
# other middleware...
]
LOGGIER = {
'API_KEY': 'your-api-key',
'API_URL': 'https://api.loggier.com/api/ingest',
'ENVIRONMENT': 'production',
'STATUSES_TO_TRACK': [500, 400, 401, 403],
'CAPTURE_REQUEST_BODY': False,
'CAPTURE_RESPONSE_BODY': True,
'MAX_BODY_SIZE': 16384,
'INCLUDE_STACKTRACE': True
}
```
#### track_endpoint Decorator
```python
from loggier.integrations.django import track_endpoint
@track_endpoint(
tags=None, # List of tags to add
statuses=None, # Status codes to track
capture_request_body=False, # Whether to capture request body
capture_response_body=False # Whether to capture response body
)
def my_view(request):
# View implementation
return HttpResponse("Hello")
```
### Flask Integration
```python
from flask import Flask
from loggier.integrations.flask import LoggierFlask
app = Flask(__name__)
loggier = LoggierFlask(api_key="your-api-key")
loggier.init_app(app)
```
### FastAPI Integration
```python
from fastapi import FastAPI
from loggier.integrations.fastapi import LoggierFastAPI
app = FastAPI()
loggier = LoggierFastAPI(api_key="your-api-key")
loggier.init_app(app)
```
## Troubleshooting
### Common Issues
1. **Logs not appearing**:
- Check API key and URL
- Ensure network connectivity
- Check if async_mode is enabled and call flush() before exit
2. **High memory usage**:
- Reduce max_batch_size
- Increase flush_interval
- Disable caching if not needed
3. **Performance impact**:
- Use async_mode=True (default)
- Be selective with STATUSES_TO_TRACK
- Use track_endpoint only on critical endpoints
- Limit body capturing (CAPTURE_REQUEST_BODY, CAPTURE_RESPONSE_BODY)
4. **Django middleware error**:
- Ensure correct middleware order
- Check LOGGIER settings in settings.py
## Best Practices
1. **Use context for structured logging**:
```python
with logger.context(user_id=123):
logger.info("User logged in")
```
2. **Add custom context to Django requests**:
```python
from loggier import _loggier_instance
if _loggier_instance:
_loggier_instance.context.update_global({
"user_id": request.user.id,
"transaction_id": "TX12345"
})
```
3. **Call flush() before application exit**:
```python
# Ensure all logs are sent
logger.flush()
```
4. **Filter sensitive data**:
```python
logger = Loggier(
api_key="your-api-key",
sensitive_fields=["password", "credit_card", "ssn"]
)
```
5. **Use decorators for performance monitoring**:
```python
@logger.trace_function(threshold_ms=100)
def slow_function():
# Performance will be logged if execution exceeds 100ms
```
Raw data
{
"_id": null,
"home_page": "https://github.com/yigitaltintas/loggier",
"name": "loggier",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "logging, error-tracking, monitoring, apm, performance",
"author": "Yigit ALTINTAS",
"author_email": "Loggier Team <info@loggier.app>",
"download_url": "https://files.pythonhosted.org/packages/8f/3b/9fdbf82df940ddb5dbcdf751096cc7167bdee0bdd63a93d86d9f2f028638/loggier-0.1.5.tar.gz",
"platform": null,
"description": "# PyLogHub/Loggier Documentation\n\n## Overview\n\nPyLogHub (Loggier) is a comprehensive logging solution for Python applications, with specialized integrations for web frameworks like Django, Flask, and FastAPI. It offers a flexible and powerful way to collect, process, and analyze logs from your applications with features like asynchronous logging, local caching, performance monitoring, and web framework integrations.\n\n## Table of Contents\n\n1. [Installation](#installation)\n2. [Core Concepts](#core-concepts)\n3. [Basic Usage](#basic-usage)\n4. [Advanced Configuration](#advanced-configuration)\n5. [Django Integration](#django-integration)\n6. [Flask Integration](#flask-integration)\n7. [FastAPI Integration](#fastapi-integration)\n8. [Performance Monitoring](#performance-monitoring)\n9. [Error Tracking](#error-tracking)\n10. [Architecture](#architecture)\n11. [API Reference](#api-reference)\n\n## Installation\n\nInstall using pip:\n\n```bash\npip install loggier\n```\n\n## Core Concepts\n\nPyLogHub/Loggier is built around these core concepts:\n\n- **Client**: The main Loggier class that handles log collection and sending\n- **Handlers**: Components that process and deliver logs (API, Async, Cache)\n- **Formatters**: Components that format logs for output\n- **Context**: A system for adding and organizing contextual information\n- **Integrations**: Framework-specific components for seamless integration\n\n## Basic Usage\n\nSimple example of using Loggier:\n\n```python\nfrom loggier import Loggier\n\n# Create a Loggier instance\nlogger = Loggier(\n api_key=\"your-api-key\",\n environment=\"development\",\n service_name=\"my-service\"\n)\n\n# Log basic messages\nlogger.info(\"Application started\")\nlogger.warning(\"Something might be wrong\", context={\"user_id\": 123})\nlogger.error(\"Something went wrong\", context={\"order_id\": \"ORD-123456\"})\n\n# Log exceptions\ntry:\n # Some code that might raise an exception\n result = 1 / 0\nexcept Exception as e:\n logger.exception(\"Error calculating result\", exception=e)\n\n# Use context for adding structured information\nwith logger.context(user_id=123, transaction_id=\"TX12345\"):\n logger.info(\"Processing transaction\")\n try:\n # Transaction processing code\n logger.info(\"Transaction completed\")\n except Exception as e:\n logger.exception(\"Transaction failed\", exception=e)\n\n# Make sure to flush logs before application exits\nlogger.flush()\n```\n\n## Advanced Configuration\n\nLoggier provides many configuration options:\n\n```python\nfrom loggier import Loggier\n\nlogger = Loggier(\n api_key=\"your-api-key\",\n project_name=\"my-project\",\n environment=\"production\",\n service_name=\"payment-service\",\n api_url=\"https://api.loggier.com/api/ingest\", # Custom API endpoint\n async_mode=True, # Send logs asynchronously\n capture_uncaught=True, # Capture uncaught exceptions\n log_level=logging.INFO, # Minimum log level\n enable_caching=True, # Cache logs when offline\n cache_dir=\"/path/to/cache\", # Custom cache directory\n max_batch_size=20, # Logs per batch\n flush_interval=5, # Auto-flush interval (seconds)\n sensitive_fields=[\"password\", \"credit_card\"], # Fields to mask\n max_retries=3, # API retry attempts\n http_timeout=5, # API timeout (seconds)\n network_check_interval=60, # Network check interval\n tags=[\"api\", \"payments\"], # Global tags\n enable_performance_monitoring=True # Enable performance monitoring\n)\n```\n\n## Django Integration\n\nLoggier offers a powerful Django integration that can track requests, responses, and errors.\n\n### Basic Setup\n\nAdd the middleware to your Django settings:\n\n```python\n# settings.py\nMIDDLEWARE = [\n # other middleware...\n 'loggier.integrations.django.LoggierDjangoMiddleware',\n # other middleware...\n]\n\n# Configure Loggier\nLOGGIER = {\n 'API_KEY': 'your-api-key-here',\n 'API_URL': 'https://api.loggier.com/api/ingest',\n 'ENVIRONMENT': 'production',\n 'TAGS': ['django', 'web'],\n 'CAPTURE_REQUEST_DATA': True,\n 'LOG_SLOW_REQUESTS': True,\n 'SLOW_REQUEST_THRESHOLD': 1.0, # seconds\n 'STATUSES_TO_TRACK': [500, 400, 401, 403], # Status codes to track\n 'CAPTURE_REQUEST_BODY': False, # Be careful with sensitive data\n 'CAPTURE_RESPONSE_BODY': True, # Capture response bodies for errors\n 'MAX_BODY_SIZE': 16384, # Max body size to capture (16KB)\n 'INCLUDE_STACKTRACE': True # Include stacktrace for errors\n}\n```\n\n### Tracking Specific Endpoints\n\nUse the `track_endpoint` decorator to track specific views or endpoints:\n\n```python\nfrom loggier.integrations.django import track_endpoint\nfrom django.http import JsonResponse\n\n# Track this endpoint with custom settings\n@track_endpoint(\n tags=['critical', 'payment'],\n capture_request_body=True,\n capture_response_body=True,\n statuses=[200, 201, 400, 500]\n)\ndef payment_process(request):\n # This endpoint will have complete request/response tracking\n return JsonResponse({\"status\": \"success\"})\n```\n\n### Django Rest Framework Integration\n\nWith Django Rest Framework, you can track specific ViewSet methods:\n\n```python\nfrom rest_framework import viewsets\nfrom loggier.integrations.django import track_endpoint\n\nclass UserViewSet(viewsets.ModelViewSet):\n queryset = User.objects.all()\n serializer_class = UserSerializer\n\n # Track only the list action\n @track_endpoint(tags=['user', 'list'])\n def list(self, request, *args, **kwargs):\n return super().list(request, *args, **kwargs)\n\n # Track the create action with body capturing\n @track_endpoint(\n tags=['user', 'create'],\n capture_request_body=True,\n capture_response_body=True\n )\n def create(self, request, *args, **kwargs):\n return super().create(request, *args, **kwargs)\n```\n\n### Complete Transaction Tracking\n\nThe Django middleware can track the complete context of HTTP transactions:\n\n1. **Request Information**:\n\n - HTTP method, path, query parameters\n - Headers (filtered for sensitive data)\n - Request body (if enabled)\n - User information\n - View/controller information\n\n2. **Response Information**:\n\n - Status code\n - Response headers\n - Response time\n - Response body (if enabled)\n\n3. **Error Information**:\n\n - Exception type and message\n - Full traceback\n - Application state at time of error\n\n4. **Custom Context**:\n - Add custom context using `logger.context.update_global()`\n\n### Example Log Output (Error):\n\n```json\n{\n \"level\": \"ERROR\",\n \"message\": \"Server error: GET /api/v1/templates/ - 500\",\n \"timestamp\": \"2025-03-09T11:41:29.000Z\",\n \"context\": {\n \"request_id\": \"3c4e6f8g-9h0i-1j2k-3l4m-5n6o7p8q9r0s\",\n \"transaction\": {\n \"request\": {\n \"method\": \"GET\",\n \"path\": \"/api/v1/templates/\",\n \"query_params\": {\n \"limit\": \"100\",\n \"offset\": \"0\"\n },\n \"user\": {\n \"user_id\": 5,\n \"username\": \"john.doe@example.com\"\n }\n },\n \"response\": {\n \"status_code\": 500,\n \"content_type\": \"text/plain; charset=utf-8\",\n \"traceback\": \"Traceback (most recent call last):...\",\n \"exception\": {\n \"type\": \"ValueError\",\n \"value\": \"Uncaught\"\n }\n }\n }\n }\n}\n```\n\n## Flask Integration\n\nLoggier provides integration with Flask:\n\n```python\nfrom flask import Flask\nfrom loggier.integrations.flask import LoggierFlask\n\napp = Flask(__name__)\n\n# Initialize Loggier\nloggier = LoggierFlask(\n api_key=\"your-api-key\",\n environment=\"production\",\n capture_request_data=True,\n log_slow_requests=True,\n slow_request_threshold=1.0\n)\n\n# Register with Flask\nloggier.init_app(app)\n\n@app.route('/')\ndef index():\n return \"Hello World!\"\n\nif __name__ == '__main__':\n app.run()\n```\n\n## FastAPI Integration\n\nLoggier integrates with FastAPI:\n\n```python\nfrom fastapi import FastAPI\nfrom loggier.integrations.fastapi import LoggierFastAPI\n\napp = FastAPI()\n\n# Initialize Loggier\nloggier = LoggierFastAPI(\n api_key=\"your-api-key\",\n environment=\"production\",\n capture_request_data=True,\n log_slow_requests=True,\n slow_request_threshold=1.0\n)\n\n# Register with FastAPI\nloggier.init_app(app)\n\n@app.get(\"/\")\ndef read_root():\n return {\"Hello\": \"World\"}\n```\n\n## Performance Monitoring\n\nLoggier includes tools for performance monitoring:\n\n```python\nfrom loggier import Loggier\n\nlogger = Loggier(\n api_key=\"your-api-key\",\n environment=\"production\",\n enable_performance_monitoring=True\n)\n\n# Track function performance\n@logger.trace_function(threshold_ms=100)\ndef process_data(data):\n # Function execution time will be tracked\n # If it exceeds 100ms, it will be logged\n return data\n\n# Track HTTP requests\n@logger.trace_http(threshold_ms=1000)\ndef fetch_external_api():\n import requests\n return requests.get(\"https://api.example.com/data\")\n\n# Track database operations\n@logger.trace_database(threshold_ms=50)\ndef get_user(user_id):\n # Database operation time will be tracked\n return User.objects.get(id=user_id)\n```\n\n## Error Tracking\n\nLoggier provides comprehensive error tracking capabilities:\n\n```python\nfrom loggier import Loggier\n\nlogger = Loggier(\n api_key=\"your-api-key\",\n environment=\"production\",\n capture_uncaught=True # Automatically capture uncaught exceptions\n)\n\n# Manually log exceptions\ntry:\n # Some code that might raise an exception\n result = 1 / 0\nexcept Exception as e:\n logger.exception(\n \"Division error\",\n exception=e,\n context={\n \"operation\": \"division\",\n \"numerator\": 1,\n \"denominator\": 0\n }\n )\n\n# Capture exceptions in functions\n@logger.capture_exceptions\ndef risky_function():\n # If this function raises an exception, it will be logged\n return 1 / 0\n```\n\n## Architecture\n\nPyLogHub/Loggier uses a modular architecture:\n\n1. **Client (Loggier)**: Main interface for applications\n2. **Handlers**:\n - **APIHandler**: Communicates with the PyLogHub API\n - **AsyncHandler**: Handles asynchronous log sending\n - **CacheHandler**: Manages local caching of logs\n3. **Formatters**:\n - **JSONFormatter**: Formats logs as JSON\n4. **Utils**:\n - **Context**: Manages contextual information\n - **Error**: Handles exception capturing\n - **Network**: Monitors network connectivity\n\n## API Reference\n\n### Loggier Class\n\nThe main client class for interacting with PyLogHub.\n\n#### Constructor\n\n```python\nLoggier(\n api_key: str,\n project_name: Optional[str] = None,\n environment: str = \"development\",\n api_url: Optional[str] = None,\n service_name: Optional[str] = None,\n async_mode: bool = True,\n capture_uncaught: bool = True,\n log_level: int = logging.INFO,\n enable_caching: bool = True,\n cache_dir: Optional[str] = None,\n max_batch_size: int = 20,\n flush_interval: int = 5,\n sensitive_fields: Optional[List[str]] = None,\n max_retries: int = 3,\n http_timeout: int = 5,\n network_check_interval: int = 60,\n tags: Optional[List[str]] = None,\n enable_performance_monitoring: bool = True\n)\n```\n\n#### Logging Methods\n\n```python\n# Basic logging methods\nlog(level: str, message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool\ndebug(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool\ninfo(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool\nwarning(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool\nerror(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool\ncritical(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool\nexception(message: str, exception: Optional[Exception] = None, context: Optional[Dict[str, Any]] = None, tags: Optional[List[str]] = None) -> bool\n\n# Context management\ncontext(**kwargs) -> Context\n\n# Performance monitoring decorators\ntrace_function(name: Optional[str] = None, threshold_ms: int = 500, tags: Optional[List[str]] = None, include_args: bool = False, include_return: bool = False, log_level: str = \"INFO\") -> Callable\ntrace_http(name: Optional[str] = None, threshold_ms: int = 1000, tags: Optional[List[str]] = None, mask_headers: Optional[List[str]] = None, mask_params: Optional[List[str]] = None, include_body: bool = False, log_level: str = \"INFO\") -> Callable\ntrace_database(name: Optional[str] = None, threshold_ms: int = 100, tags: Optional[List[str]] = None, include_params: bool = False, log_level: str = \"INFO\") -> Callable\n\n# Utility methods\nflush(timeout: Optional[float] = None) -> bool\nget_stats() -> Dict[str, Any]\nshutdown(timeout: Optional[float] = None) -> None\n```\n\n### Django Integration\n\n#### LoggierDjangoMiddleware\n\n```python\n# In settings.py\nMIDDLEWARE = [\n 'loggier.integrations.django.LoggierDjangoMiddleware',\n # other middleware...\n]\n\nLOGGIER = {\n 'API_KEY': 'your-api-key',\n 'API_URL': 'https://api.loggier.com/api/ingest',\n 'ENVIRONMENT': 'production',\n 'STATUSES_TO_TRACK': [500, 400, 401, 403],\n 'CAPTURE_REQUEST_BODY': False,\n 'CAPTURE_RESPONSE_BODY': True,\n 'MAX_BODY_SIZE': 16384,\n 'INCLUDE_STACKTRACE': True\n}\n```\n\n#### track_endpoint Decorator\n\n```python\nfrom loggier.integrations.django import track_endpoint\n\n@track_endpoint(\n tags=None, # List of tags to add\n statuses=None, # Status codes to track\n capture_request_body=False, # Whether to capture request body\n capture_response_body=False # Whether to capture response body\n)\ndef my_view(request):\n # View implementation\n return HttpResponse(\"Hello\")\n```\n\n### Flask Integration\n\n```python\nfrom flask import Flask\nfrom loggier.integrations.flask import LoggierFlask\n\napp = Flask(__name__)\nloggier = LoggierFlask(api_key=\"your-api-key\")\nloggier.init_app(app)\n```\n\n### FastAPI Integration\n\n```python\nfrom fastapi import FastAPI\nfrom loggier.integrations.fastapi import LoggierFastAPI\n\napp = FastAPI()\nloggier = LoggierFastAPI(api_key=\"your-api-key\")\nloggier.init_app(app)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Logs not appearing**:\n\n - Check API key and URL\n - Ensure network connectivity\n - Check if async_mode is enabled and call flush() before exit\n\n2. **High memory usage**:\n\n - Reduce max_batch_size\n - Increase flush_interval\n - Disable caching if not needed\n\n3. **Performance impact**:\n\n - Use async_mode=True (default)\n - Be selective with STATUSES_TO_TRACK\n - Use track_endpoint only on critical endpoints\n - Limit body capturing (CAPTURE_REQUEST_BODY, CAPTURE_RESPONSE_BODY)\n\n4. **Django middleware error**:\n - Ensure correct middleware order\n - Check LOGGIER settings in settings.py\n\n## Best Practices\n\n1. **Use context for structured logging**:\n\n ```python\n with logger.context(user_id=123):\n logger.info(\"User logged in\")\n ```\n\n2. **Add custom context to Django requests**:\n\n ```python\n from loggier import _loggier_instance\n if _loggier_instance:\n _loggier_instance.context.update_global({\n \"user_id\": request.user.id,\n \"transaction_id\": \"TX12345\"\n })\n ```\n\n3. **Call flush() before application exit**:\n\n ```python\n # Ensure all logs are sent\n logger.flush()\n ```\n\n4. **Filter sensitive data**:\n\n ```python\n logger = Loggier(\n api_key=\"your-api-key\",\n sensitive_fields=[\"password\", \"credit_card\", \"ssn\"]\n )\n ```\n\n5. **Use decorators for performance monitoring**:\n ```python\n @logger.trace_function(threshold_ms=100)\n def slow_function():\n # Performance will be logged if execution exceeds 100ms\n ```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Log management and error tracking library for modern Python applications.",
"version": "0.1.5",
"project_urls": {
"Documentation": "https://docs.loggier.app",
"Homepage": "https://loggier.app",
"Issues": "https://github.com/loggier/loggier/issues",
"Repository": "https://github.com/loggier/loggier"
},
"split_keywords": [
"logging",
" error-tracking",
" monitoring",
" apm",
" performance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1d0f08f70e9f7a28bb8e63ce26daf08b2d54c99f6780d4c9701788020e33cd46",
"md5": "de4617adf1d58a740f26a8da935fe637",
"sha256": "e1ba8c889f04860429e4bc040f23d1b3486896d602cd032df0d3f86d37695a2a"
},
"downloads": -1,
"filename": "loggier-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de4617adf1d58a740f26a8da935fe637",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 48695,
"upload_time": "2025-03-09T16:53:08",
"upload_time_iso_8601": "2025-03-09T16:53:08.824582Z",
"url": "https://files.pythonhosted.org/packages/1d/0f/08f70e9f7a28bb8e63ce26daf08b2d54c99f6780d4c9701788020e33cd46/loggier-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8f3b9fdbf82df940ddb5dbcdf751096cc7167bdee0bdd63a93d86d9f2f028638",
"md5": "09597ceaa7ebd168c8c3f83cb6c8e58b",
"sha256": "d03be764eea6d6f5beebc7dc67e316a10d75cd5cc8063c0713cb4b134cc722da"
},
"downloads": -1,
"filename": "loggier-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "09597ceaa7ebd168c8c3f83cb6c8e58b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 45887,
"upload_time": "2025-03-09T16:53:10",
"upload_time_iso_8601": "2025-03-09T16:53:10.406550Z",
"url": "https://files.pythonhosted.org/packages/8f/3b/9fdbf82df940ddb5dbcdf751096cc7167bdee0bdd63a93d86d9f2f028638/loggier-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-09 16:53:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yigitaltintas",
"github_project": "loggier",
"github_not_found": true,
"lcname": "loggier"
}
JSON
