Metadata-Version: 2.4
Name: secureapp-python-agent
Version: 26.5.0rc4
Summary: Splunk SecureApp OpenTelemetry Extension for Python applications
Author-email: Splunk <support@splunk.com>
License-Expression: LicenseRef-Proprietary
Keywords: observability,opentelemetry,security,monitoring,splunk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-api<1.40,>=1.27.0
Requires-Dist: opentelemetry-sdk<1.40,>=1.27.0
Requires-Dist: opentelemetry-exporter-otlp<1.40,>=1.27.0
Requires-Dist: protobuf>=5.0; python_version >= "3.14"
Provides-Extra: dev
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Requires-Dist: pytest-testmon>=2.1.3; extra == "dev"
Requires-Dist: mypy>=1.16.1; extra == "dev"
Requires-Dist: ruff>=0.12.1; extra == "dev"
Requires-Dist: coverage[toml]>=7.0.0; extra == "dev"
Requires-Dist: tox>=4.27.0; extra == "dev"
Requires-Dist: build>=1.2.2.post1; extra == "dev"
Requires-Dist: pip-tools>=7.4.1; extra == "dev"
Requires-Dist: setuptools-scm[toml]>=8.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: pytest-benchmark>=4.0.0; extra == "benchmark"
Requires-Dist: memory-profiler>=0.61.0; extra == "benchmark"
Requires-Dist: psutil>=5.9.0; extra == "benchmark"
Requires-Dist: memray>=1.10.0; extra == "benchmark"
Provides-Extra: all
Requires-Dist: secureapp-python-agent[benchmark,dev]; extra == "all"
Dynamic: license-file

# Splunk SecureApp OpenTelemetry Extension

OpenTelemetry Python extension for integrating Splunk SecureApp with OpenTelemetry.
This extension monitors runtime dependencies and reports them via OpenTelemetry logs.

For more information, please refer to this wiki page: https://confluence.corp.appdynamics.com/spaces/APMJAVA/pages/7999681/SecureApp+For+Python

## Quick Start

```bash
# Development setup
make venv-install

# Run tests (single Python version)
make test

# Run tests across all Python versions
make tox

# Run all quality checks
make all
```

## Installation

```bash
# Install from PyPI
pip install secureapp-python-agent

# Install in development mode with dev dependencies
pip install -e .[dev]
```

## Usage

The extension can be used in two ways: zero-configuration instrumentation or
manual integration.

### Zero-Configuration with OpenTelemetry Instrumentation

```bash
# Install with OpenTelemetry instrumentation
pip install secureapp-python-agent opentelemetry-distro[otlp]

# Run your application with automatic instrumentation
opentelemetry-instrument python your_app.py
```

### Manual Integration

```python
from splunk_secureapp_opentelemetry_extension import start_monitoring, stop_monitoring

# Start monitoring at application initialization
start_monitoring()

# ... your application code ...

# Optional: Stop monitoring during application shutdown
stop_monitoring()
```

## Configuration

The extension can be configured using environment variables:

| Environment Variable                        | Default | Description                                               |
|---------------------------------------------|---------|-----------------------------------------------------------|
| `SPLUNK_SECUREAPP_AGENT_ENABLED`            | `true`  | Enable or disable the agent completely                    |
| `OTEL_LOGS_EXPORTER`                        | `otlp`  | Log exporter type: `otlp`, `console`, or `none`           |
| `SPLUNK_SECUREAPP_DEPENDENCY_INITIAL_DELAY` | `60.0`  | Initial delay (seconds) before dependency tracking starts |
| `SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL` | `86400` | Interval (seconds) between dependency scans (24 hours)    |

Example configuration:

```bash
# Configure with environment variables
export OTEL_LOGS_EXPORTER=console
export SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL=600.0
opentelemetry-instrument python your_app.py
```

## Features

### Runtime Dependency Monitoring

The extension monitors third-party Python packages loaded at runtime and reports
them through OpenTelemetry logs with:
- Package name and version
- Import timestamp
- Standard library exclusion for performance optimization
- Low overhead (<10MB memory, <100ms startup impact)

### OpenTelemetry Integration

- Sends dependency data as structured logs via configurable exporters
- Compatible with the OpenTelemetry Collector and Splunk Observability backends
- Lightweight implementation with optimized performance

## Compatibility

### OpenTelemetry Versions

The extension is compatible with OpenTelemetry versions 1.27.0 through 1.39.x.

**Supported and tested range**: `1.27.0` - `<1.40` (tested: 1.27.0, 1.30.0, 1.35.0, 1.38.0, 1.39.0, 1.39.1)

The agent automatically adapts to both legacy (pre-1.39) and modern (1.39+) Logs APIs, providing:
- Seamless compatibility across the tested version range
- Backward compatibility with OpenTelemetry 1.27.0+
- No version conflicts with other OpenTelemetry packages requiring 1.39.x
- Independent upgrade paths for OpenTelemetry and SecureApp agent

**Note**: OpenTelemetry 1.39.0 introduced breaking changes to the Logs API. This agent handles both API versions transparently using version-adaptive code.

### Python Versions

Supported Python versions:
- Python 3.10
- Python 3.11
- Python 3.12
- Python 3.13
- Python 3.14

## Performance Considerations

The SecureApp agent is designed with minimal performance impact:
- Startup overhead: <100ms
- Memory overhead: <10MB
- Optimizations:
  - Lazy imports for better startup performance
  - Standard library detection to avoid unnecessary scanning
  - Configurable scan intervals
  - Efficient batch processing for telemetry data

## Development

```bash
make help                 # Show all available commands
make venv-install         # Setup development environment
make test                 # Run tests (current Python)
make test-cov             # Run tests with coverage
make tox                  # Run tests across all Python versions
make lint                 # Run linting with auto-fix
make format               # Format code
make typecheck            # Type checking
make build                # Build package
make clean                # Clean build artifacts
make license-check        # Check and add license headers
make update-deps          # Update dependencies to latest versions
make all                  # Run lint, typecheck, and test
```

## Testing

- Supports Python 3.10+
- All tests must mock expensive operations (e.g., sys.modules scanning, OpenTelemetry exporters)
- Minimum 85% test coverage required

```bash
# Quick testing (current Python)
make test                 # Basic tests
make test-cov             # With coverage report

# Comprehensive testing (all Python versions)
make tox                  # Uses tox for multi-version testing

# OpenTelemetry compatibility testing
make test-otel-versions   # Test with different OTel versions
```

## Dependency Management

```bash
# Update all dependencies to latest versions
make update-deps

# After updating, verify compatibility
make test
make tox
```

## Workflow

```bash
# 1. Daily development (fast feedback)
make all

# 2. Before committing (comprehensive)
make tox

# 3. Dependency updates (monthly)
make update-deps && make tox

# 4. Clean build
make clean build
```

## Project Structure

```
├── scripts/
│   ├── check_license.py    # License header automation
│   └── update_deps.py      # Dependency update automation
├── src/splunk_secureapp_opentelemetry_extension/
│   ├── __init__.py        # Package entry point (exposes only public APIs)
│   ├── agent.py           # SecureApp agent implementation
│   ├── dependency_analyzer.py # Runtime dependency analysis
│   └── environment_variables.py # Environment variable constants
├── tests/                 # Test suite (all expensive operations mocked)
├── pyproject.toml         # Project configuration
├── Makefile               # Development commands
└── README.md              # This file
