Metadata-Version: 2.4
Name: pensivium
Version: 0.1.4
Summary: The official client library for the Pensieve APM.
Author-email: Harshita Jain <harshitajn18@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Harshita Jain
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Requires-Dist: requests
Dynamic: license-file

# pensieve-client 🚀

[![PyPI Version](https://img.shields.io/pypi/v/pensieve.svg)](https://pypi.org/project/pensieve/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A lightweight, Django-first APM and error-tracking client for the **Pensieve** observability platform.

This package is a client library designed to be installed in any Django project. It automatically monitors your application's performance and tracks exceptions.

Its main feature is a **fully integrated Django Admin dashboard**—it adds a "Performance Insights" page directly to your project's *own* admin panel, allowing you to see your site's health without ever leaving your workspace.

## Features ✨

* **📈 Integrated Admin Dashboard:** View error and performance charts directly in your site's `/admin/`.
* **🐛 Automatic Exception Tracking:** Captures and groups unhandled exceptions with full stack traces.
* **⏱️ Performance Monitoring:** Tracks request/response times for all your views.
* **📊 Interactive Charts:** Provides a "Top 5 Slowest Endpoints" summary and interactive, filterable line charts for drilling down into a specific URL's performance history.
* **⚙️ Lightweight & Configurable:** Designed to be low-overhead. Automatically excludes its own dashboard URLs from being monitored.

## Installation


1.  Install the package using pip:
    ```bash
    pip install pensieve
    ```

2.  Add `pensieve_client` to your `INSTALLED_APPS` in `settings.py`.
    ```python
    # settings.py

    INSTALLED_APPS = [
        # ... other apps
        'django.contrib.admin',
        'django.contrib.auth',
        # ...
        'pensieve_client',
    ]
    ```

3.  Add the Pensieve middleware to your `settings.py`. It's recommended to place it at the **bottom** of the list to ensure it correctly wraps your views.
    ```python
    # settings.py

    MIDDLEWARE = [
        'django.middleware.security.SecurityMiddleware',
        'django.contrib.sessions.middleware.SessionMiddleware',
        # ... other middleware
        'pensieve_client.middleware.PensieveMiddleware', # <-- Add this
    ]
    ```

## Configuration

Visit pensieve.harshitajn.tech and register with email, password and name.
Create a project and you will get an api key for the project.

Add the following settings to your project's `settings.py` file:

```python
# settings.py

# Your unique project API key from your Pensieve server dashboard
PENSIEVE_API_KEY = "your-project-api-key-from-pensieve"

# This is the exact url you have to mention in settings.py to get the metrics
PENSIEVE_URL = "[https://pensieve.harshitanjn.tech/api](https://pensieve.harshitajn.tech/api)" 

# (Optional) A list of URL paths to exclude from performance tracking.
# It's a good idea to exclude the admin panel to reduce noise.
PENSIEVEGRID_EXCLUDE_URLS = [
    '/admin/',
    '/__debug__/',
]
```


## How to Use 📊

Once the package is installed and configured:

1.  Run your Django project.

2.  Log in to your project's admin panel (e.g., `http://127.0.0.1:8000/admin/`).

3.  In the admin homepage, you will see a new section (likely "AUTHENTICATION AND AUTHORIZATION") with a link named "Pensieve Dashboards".

4.  Click this link to view your project's performance and error data, which is displayed directly within your own admin.


## License
This project is licensed under the MIT License. See the LICENSE file for details.
