loggier


Nameloggier JSON
Version 0.1.5 PyPI version JSON
download
home_pagehttps://github.com/yigitaltintas/loggier
SummaryLog management and error tracking library for modern Python applications.
upload_time2025-03-09 16:53:10
maintainerNone
docs_urlNone
authorYigit ALTINTAS
requires_python>=3.6
licenseMIT
keywords logging error-tracking monitoring apm performance
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.49318s