Skip to main content

OpenTelemetry Aerospike Instrumentation

PyPI - Version Python Version License

OpenTelemetry instrumentation for the Aerospike Python Client.

This library enables automatic tracing of Aerospike database operations, providing visibility into your application's database interactions.

Installation

pip install opentelemetry-instrumentation-aerospike

QuickStart

Requirements

  • Python >= 3.9
  • aerospike >= 17.2.0
  • opentelemetry-api >= 1.12
  • opentelemetry-instrumentation >= 0.40b0

Usage

Basic Usage

import aerospike
from opentelemetry.instrumentation.aerospike import AerospikeInstrumentor

# Instrument Aerospike BEFORE creating any clients
AerospikeInstrumentor().instrument()

# Create and use client as normal - all operations will be traced
config = {'hosts': [('127.0.0.1', 3000)]}
client = aerospike.client(config)
client.connect()

# Operations are now automatically traced
client.put(('test', 'demo', 'key1'), {'name': 'John', 'age': 30})
key, meta, bins = client.get(('test', 'demo', 'key1'))

client.close()

With Custom Tracer Provider

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

# Setup tracer provider
provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# Instrument with custom tracer provider
AerospikeInstrumentor().instrument(tracer_provider=provider)

Using Hooks

You can use hooks to customize span attributes or add custom logic:

def request_hook(span, operation, args, kwargs):
    """Called before each database operation."""
    span.set_attribute("custom.request.id", get_request_id())

def response_hook(span, operation, result):
    """Called after a successful operation."""
    if isinstance(result, tuple) and len(result) >= 3:
        span.set_attribute("custom.record.bins", len(result[2]))

def error_hook(span, operation, exception):
    """Called when an operation fails."""
    span.set_attribute("custom.error.code", getattr(exception, 'code', -1))

AerospikeInstrumentor().instrument(
    request_hook=request_hook,
    response_hook=response_hook,
    error_hook=error_hook
)

Capturing Record Keys

By default, record keys are not captured for security reasons. To enable:

AerospikeInstrumentor().instrument(capture_key=True)

⚠️ Security Warning: Only enable key capture in development or when keys don't contain sensitive information.

Uninstrumenting

instrumentor = AerospikeInstrumentor()
instrumentor.instrument()

# ... use client ...

# Remove instrumentation
instrumentor.uninstrument()

Span Attributes

The instrumentation follows OpenTelemetry Semantic Conventions for Database.

Standard Attributes

Attribute Description Example
db.system Database system identifier aerospike
db.namespace Aerospike namespace test
db.collection.name Aerospike set name users
db.operation.name Operation name PUT, GET, QUERY
db.operation.batch.size Batch operation size 100
server.address Server hostname/IP 127.0.0.1
server.port Server port 3000

Error Attributes

Attribute Description Example
error.type Exception class name RecordNotFound
db.response.status_code Aerospike error code 2

Aerospike-Specific Attributes

Attribute Description Example
db.aerospike.key Record key (if enabled) user123
db.aerospike.generation Record generation 5
db.aerospike.ttl Record TTL in seconds 86400
db.aerospike.udf.module UDF module name mymodule
db.aerospike.udf.function UDF function name myfunction

Span Naming

Spans are named following the convention: {OPERATION} {namespace}.{set}

Examples:

  • PUT test.users
  • GET production.orders
  • BATCH GET test.demo
  • QUERY test.events
  • SCAN production.logs

Supported Operations

Single Record Operations

  • put, get, select, exists, remove, touch
  • operate, append, prepend, increment

Batch Operations

  • batch_read, batch_write, batch_operate, batch_remove, batch_apply

Query/Scan Operations

  • query, scan

UDF Operations

  • apply, scan_apply, query_apply

Admin Operations

  • truncate, info_all

Async Pattern Support

The instrumentation works with async wrapper patterns commonly used in production:

import asyncio
import functools
from concurrent.futures import ThreadPoolExecutor

class AsyncAerospikeClient:
    def __init__(self, client):
        self._client = client
        self._executor = ThreadPoolExecutor(max_workers=10)

    def __getattr__(self, attr):
        async def method(*args, **kwargs):
            loop = asyncio.get_running_loop()
            return await loop.run_in_executor(
                self._executor,
                functools.partial(getattr(self._client, attr), *args, **kwargs)
            )
        return method

# Instrument before creating clients
AerospikeInstrumentor().instrument()

# Create sync client (instrumented)
config = {'hosts': [('127.0.0.1', 3000)]}
sync_client = aerospike.client(config)
sync_client.connect()

# Wrap with async pattern
async_client = AsyncAerospikeClient(sync_client)

# Async operations are traced!
async def main():
    await async_client.put(('test', 'demo', 'key1'), {'data': 'value'})
    result = await async_client.get(('test', 'demo', 'key1'))

Development

Setup

# Clone repository
git clone https://github.com/your-repo/opentelemetry-instrumentation-aerospike.git
cd opentelemetry-instrumentation-aerospike

# Create virtual environment
uv venv
source .venv/bin/activate

# Install with dev dependencies
uv pip install -e ".[dev]"

Running Tests

# Start Aerospike (Docker)
docker run -d --name aerospike-test -p 3000:3000 aerospike/aerospike-server:latest

# Run integration tests
pytest tests/test_aerospike_integration.py -v

# Run with coverage
pytest --cov=opentelemetry.instrumentation.aerospike --cov-report=html

Code Quality

# Format code
black src tests
isort src tests

# Lint
ruff check src tests

# Type check
mypy src

License

Apache License 2.0

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Metadata

Release files for opentelemetry-instrumentation-aerospike 0.2.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opentelemetry-instrumentation-aerospike 0.2.5
File Size Uploaded Provenance Actions
opentelemetry_instrumentation_aerospike-0.2.5.tar.gz 21.4 kB With provenance Details for opentelemetry_instrumentation_aerospike-0.2.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opentelemetry-instrumentation-aerospike 0.2.5
File Interpreter ABI Platform Actions
opentelemetry_instrumentation_aerospike-0.2.5-py3-none-any.whl Python 3 none any Details for opentelemetry_instrumentation_aerospike-0.2.5-py3-none-any.whl

Total release size: 35.5 kB

Release files / opentelemetry_instrumentation_aerospike-0.2.5.tar.gz

Download URL opentelemetry_instrumentation_aerospike-0.2.5.tar.gz
Size 21.4 kB
Tags Source
SHA-256 checksum
How to use checksums
5d8f0f8929995873d04b33020b254c50874dfdfd7a47afc362f663cee312e782
BLAKE2b-256 checksum
How to use checksums
db3a21c435270061ea0ec1816170c8d0d4d366a728aa24b746520254eae5c09b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.

Transparency log

Release files / opentelemetry_instrumentation_aerospike-0.2.5-py3-none-any.whl

Download URL opentelemetry_instrumentation_aerospike-0.2.5-py3-none-any.whl
Size 14.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6297fa374229f4d3e62608c338095912d8a36a9b970497b344fc0e588d330cb7
BLAKE2b-256 checksum
How to use checksums
00597913987193e51b29d826282c94de282dcfc58dd74c3dc93014e88a2490eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.

Transparency log

Security for opentelemetry-instrumentation-aerospike 0.2.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for opentelemetry_instrumentation_aerospike-0.2.5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page