Metadata-Version: 2.4
Name: thelab-instrumentation
Version: 0.4.0
Summary: Shared instrumentation and monitoring code for Django projects
Project-URL: Homepage, https://gitlab.com/thelabnyc/thelab-instrumentation
Project-URL: Documentation, https://gitlab.com/thelabnyc/thelab-instrumentation
Project-URL: Repository, https://gitlab.com/thelabnyc/thelab-instrumentation
Author-email: thelab <thelabdev@thelab.co>
License: ISC
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: django-stubs-ext>=5.2.9
Requires-Dist: django<6.0,>=5.2
Requires-Dist: sentry-sdk>=2.51.0
Requires-Dist: typing-extensions>=4.15.0
Provides-Extra: cloudwatch
Requires-Dist: boto3>=1.42.38; extra == 'cloudwatch'
Provides-Extra: rq
Requires-Dist: django-rq>=3.2.2; extra == 'rq'
Requires-Dist: rq>=2.6.1; extra == 'rq'
Description-Content-Type: text/markdown

# thelab-instrumentation

[![Latest Release](https://gitlab.com/thelabnyc/thelab-instrumentation/-/badges/release.svg)](https://gitlab.com/thelabnyc/thelab-instrumentation/-/releases)
[![pipeline status](https://gitlab.com/thelabnyc/thelab-instrumentation/badges/master/pipeline.svg)](https://gitlab.com/thelabnyc/thelab-instrumentation/-/commits/master)
[![coverage report](https://gitlab.com/thelabnyc/thelab-instrumentation/badges/master/coverage.svg)](https://gitlab.com/thelabnyc/thelab-instrumentation/-/commits/master)

A fully type-safe instrumentation and monitoring library for Django projects. This package provides:

- Metrics collection and reporting to various backends (CloudWatch, Logging)
- RQ queue monitoring
- Clean, type-safe API with comprehensive mypy typing

## Installation

Install the package using your package manager of choice:

```sh
# Using uv (recommended)
uv pip install thelab-instrumentation

# Using pip
pip install thelab-instrumentation
```

Add the package to your Django `INSTALLED_APPS`:

```py
INSTALLED_APPS = [
    # ...
    'thelabinstrumentation',
    'thelabinstrumentation.rq',  # Include if using RQ monitoring
    # ...
]
```

## Configuration

Configure the library in your Django settings:

```py
THELAB_INSTRUMENTATION = {
    # Metrics backend (default: logging backend)
    'BACKEND': 'thelabinstrumentation.backends.cloudwatch.CloudWatchBackend',

    # Backend-specific options
    'OPTIONS': {
        # Cloudwatch Backend
        "namespace": 'MyApplication',
    },

    # Update interval in seconds (default: 60)
    'UPDATE_INTERVAL': 60,

    # Global dimensions added to all metrics
    'DIMENSIONS': {
        'Environment': 'production',
        'Application': 'my-app',
    },
}
```

## Development

### Setup Development Environment

```sh
# Clone the repository
git clone https://gitlab.com/thelabnyc/thelab-instrumentation.git
cd thelab-instrumentation

# Install dependencies
uv sync

# Install pre-commit hooks
pre-commit install
```

### Run Tests

```sh
# Run all tests
uv run tox

# Run mypy type checking
uv run mypy thelabinstrumentation/

# Run linting
uv run ruff check
```
