secureapp-python-agent 26.5.0rc4

Splunk SecureApp OpenTelemetry Extension for Python applications

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

# 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

# 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

# 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

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:

# 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

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

# 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

# Update all dependencies to latest versions
make update-deps

# After updating, verify compatibility
make test
make tox

Workflow

# 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