Metadata-Version: 2.4
Name: justanalytics-python
Version: 0.1.1
Summary: Official Python SDK for JustAnalytics — end-to-end observability (traces, errors, logs, metrics)
Project-URL: Homepage, https://justanalytics.app
Project-URL: Documentation, https://justanalytics.app/docs
Project-URL: Repository, https://github.com/velocitydigitallabs/justanalytics
Author-email: Velocity Digital Labs LLC <support@velocitydigitallabs.com>
License-Expression: MIT
Keywords: analytics,apm,errors,logs,monitoring,observability,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: urllib3>=1.26
Provides-Extra: dev
Requires-Dist: flask>=2.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: requests>=2.20; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=3.2; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: starlette>=0.20; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0; extra == 'flask'
Provides-Extra: requests
Requires-Dist: requests>=2.20; extra == 'requests'
Description-Content-Type: text/markdown

# justanalytics-python

Official Python SDK for [JustAnalytics](https://justanalytics.app) — end-to-end observability (traces, errors, logs, metrics).

## Installation

```bash
pip install justanalytics-python
```

With framework extras:

```bash
pip install justanalytics-python[django]
pip install justanalytics-python[flask]
pip install justanalytics-python[fastapi]
pip install justanalytics-python[requests]
```

## Quick Start

```python
import justanalytics

justanalytics.init(
    site_id="site_abc123",
    api_key="ja_sk_your_api_key_here",
    service_name="api-server",
    environment="production",
)

# Traced spans (context manager)
with justanalytics.start_span("process-order") as span:
    span.set_attribute("order.id", "12345")
    result = process_order()

# Decorator
@justanalytics.span(op="db.query")
def get_user(user_id: str):
    return db.query(...)

# Error capture
try:
    risky_operation()
except Exception as e:
    justanalytics.capture_exception(e, tags={"module": "payments"})

# Message capture
justanalytics.capture_message("Deployment complete", level="info")

# User context
justanalytics.set_user(id="user-123", email="alice@example.com")

# Tags
justanalytics.set_tag("feature", "checkout")

# Structured logging
justanalytics.log("info", "User logged in", {"userId": "u123"})

# Metrics
justanalytics.record_metric("custom.queue_size", 42, {"queue": "emails"})

# Flush before shutdown
justanalytics.flush()
justanalytics.close()
```

## Framework Integrations

### Django

```python
# settings.py
MIDDLEWARE = [
    "justanalytics.integrations.django.JustAnalyticsMiddleware",
    # ... other middleware
]
```

### Flask

```python
from flask import Flask
from justanalytics.integrations.flask import JustAnalyticsMiddleware

app = Flask(__name__)
JustAnalyticsMiddleware(app)
```

### FastAPI

```python
from fastapi import FastAPI
from justanalytics.integrations.fastapi import JustAnalyticsMiddleware

app = FastAPI()
app.add_middleware(JustAnalyticsMiddleware)
```

### requests library

```python
from justanalytics.integrations.requests import RequestsIntegration

integration = RequestsIntegration(service_name="my-service")
integration.enable()
# All requests.get/post calls are now traced
```

### Python logging bridge

```python
import logging
from justanalytics.integrations.logging import JustAnalyticsHandler

handler = JustAnalyticsHandler(level=logging.WARNING)
logging.getLogger().addHandler(handler)
```

## W3C Trace Context

```python
from justanalytics import parse_traceparent, serialize_traceparent

# Parse incoming header
data = parse_traceparent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")

# Serialize outgoing header
header = serialize_traceparent(trace_id, span_id, sampled=True)
```

## License

MIT
