Metadata-Version: 2.4
Name: edgepulse
Version: 0.1.3
Summary: EdgePulse Python SDK for edge functions monitoring and observability
Author-email: Jeremy Trips <hello@jeremytrips.be>
Maintainer-email: Jeremy Trips <hello@jeremytrips.be>
License: MIT
Project-URL: Homepage, https://github.com/edgepulse/sdk-python
Project-URL: Documentation, https://docs.edgepulse.com/sdk/python
Project-URL: Repository, https://github.com/edgepulse/sdk-python.git
Project-URL: Issues, https://github.com/edgepulse/sdk-python/issues
Project-URL: Changelog, https://github.com/edgepulse/sdk-python/blob/main/CHANGELOG.md
Keywords: monitoring,observability,telemetry,performance,tracking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Dynamic: license-file

# EdgePulse Python SDK

[![PyPI version](https://badge.fury.io/py/edgepulse.svg)](https://badge.fury.io/py/edgepulse)
[![Python Support](https://img.shields.io/pypi/pyversions/edgepulse.svg)](https://pypi.org/project/edgepulse/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The EdgePulse Python SDK provides monitoring and observability capabilities for Python applications. It allows you to track function executions, capture timing data, handle errors, and send telemetry to EdgePulse services.

## Installation

Install the EdgePulse SDK using pip:

```bash
pip install edgepulse
```

## Quick Start

1. **Set up your environment**:
   ```bash
   export EDGEPULSE_PROJECT_KEY="your-api-key-here"
   export EDGEPULSE_API_URL="https://api.edgepulse.com/api/Invocation"  # Optional
   ```

2. **Use the decorator to monitor functions**:
   ```python
   from Edgepulse import with_edgepulse

   @with_edgepulse
   def my_function(x, y):
       """Your function logic here."""
       return x + y

   # The function will now be monitored automatically
   result = my_function(1, 2)
   ```

## Features

- **Zero-configuration monitoring**: Simple decorator-based approach
- **Automatic timing**: Captures function execution duration
- **Error tracking**: Records exceptions with full stack traces  
- **Flexible telemetry**: Sends data to configurable EdgePulse endpoints
- **Type safety**: Full type hints for better development experience
- **No external dependencies**: Uses only Python standard library

## Configuration

The SDK uses environment variables for configuration:

- `EDGEPULSE_PROJECT_KEY` (required): Your EdgePulse API key
- `EDGEPULSE_API_URL` (optional): EdgePulse API endpoint (defaults to https://edgepulse.jeremytrips.be)
- `EDGEPULSE_DEBUG` (optional): Set to `1`, `true`, or `True` to mark invocations as debug (suppresses error notifications)
- `EDGEPULSE_CAPTURE_ARGS` (optional): Set to `1`, `true`, or `True` to capture function arguments in error events (default: `False`)

## Advanced Usage

### Capturing Function Arguments

By default, function arguments are **not captured** for privacy reasons. To enable argument capture in error events:

```python
from Edgepulse import configure

# Enable globally
configure(api_key="your-key", capture_args=True)

@with_edgepulse
def process_payment(amount, card_number):
    # If an error occurs, arguments will be captured
    # Sensitive parameters like 'card_number' containing 'password', 'token',
    # 'secret', 'api_key', or 'auth' are automatically redacted
    pass
```

Or using environment variables:

```bash
export EDGEPULSE_CAPTURE_ARGS=true
```

**Security & Privacy:**
- Arguments are **only captured when errors occur** (not for successful invocations)
- Sensitive parameter names are **automatically redacted** (password, token, secret, api_key, auth patterns)
- Argument data is **size-limited to 10KB** (truncated if larger)
- Non-serializable objects are replaced with `[Non-serializable: TypeName]` placeholders


### Per-Function Configuration

```python
from Edgepulse import with_edgepulse, EdgePulseConfig

# Configure per function
@with_edgepulse(cfg=EdgePulseConfig(
    api_key="your-key",
    capture_args=True
))
def critical_function(data):
    # This function will capture arguments on errors
    pass
```

### Custom HTTP client

```python
from Edgepulse import WebClient, store_invocation

# Use a custom client with different timeout
client = WebClient("https://api.edgepulse.com/api/Invocation", timeout=30)
store_invocation(invocation, client=client)
```

## Development

### Setting up development environment

```bash
git clone https://github.com/edgepulse/sdk-python.git
cd sdk-python
pip install -e ".[dev]"
```

## Requirements

- Python 3.9+

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- Documentation: Does not exists yet
- Issues: [https://github.com/jeremytrips/edgepulse.py/issues](https://github.com/edgepulse/sdk-python/issues)
- Email: jeremy.trips@gmail.com

## Contributing

We welcome contributions!
