OpenTelemetry pymemcache Instrumentation

0.62b0 · active · verified Sat Apr 11

This library provides OpenTelemetry instrumentation for `pymemcache`, enabling automatic tracing of Memcached client operations. It is part of the `opentelemetry-python-contrib` project, which generally follows a monthly release cadence. As of version 0.62b0, the instrumentation libraries within `opentelemetry-python-contrib` are considered beta and may undergo breaking changes.

Warnings

gotcha OpenTelemetry Python Contrib instrumentations are currently in beta, which means they are not recommended for production environments. Breaking changes to APIs or telemetry output may occur in future releases without major version bumps.
Fix: Monitor release notes for breaking changes. Exercise caution when deploying to production and consider locking dependency versions.
gotcha When using pre-forking web servers (e.g., Gunicorn with `workers > 1`), auto-instrumentation, particularly for metrics, can lead to inconsistent or broken telemetry due to issues with background threads and locks being duplicated or not properly initialized in child processes after forking.
Fix: For Gunicorn, consider using a single worker (`--workers 1`), or implement programmatic instrumentation where you initialize the OpenTelemetry SDK in each worker process after forking. For metrics, using a `PeriodicExportingMetricReader` with one OTLP worker per process to push to a Prometheus server is also recommended.
gotcha Running applications with Flask's debug mode enabled (which uses a reloader) can interfere with OpenTelemetry's instrumentation, causing it to break or not function as expected.
Fix: Disable Flask's debug mode when using OpenTelemetry instrumentation, especially in environments where robust tracing is critical.
gotcha The OpenTelemetry semantic conventions, which define the names and attributes of telemetry data, are still evolving. This means that the attributes recorded by `opentelemetry-instrumentation-pymemcache` might change in future versions, potentially breaking dashboards, alerts, or analysis tools configured against current attribute names.
Fix: Stay informed about semantic convention updates from the OpenTelemetry project. Be prepared to update monitoring configurations as semantic conventions stabilize and are adopted by the instrumentation.

Install

pip install opentelemetry-instrumentation-pymemcache pymemcache opentelemetry-sdk opentelemetry-exporter-otlp Install with core OTel SDK and OTLP exporter

Imports

PymemcacheInstrumentor

from opentelemetry.instrumentation.pymemcache import PymemcacheInstrumentor

Quickstart

This example sets up a basic OpenTelemetry tracing environment with an OTLP exporter, instruments the `pymemcache` library, and then demonstrates typical `pymemcache` client operations. Spans for `set`, `get`, and `delete` operations will be generated and sent to the configured OTLP endpoint (e.g., an OpenTelemetry Collector).

import os
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
from opentelemetry.instrumentation.pymemcache import PymemcacheInstrumentor
from pymemcache.client.base import Client

# Configure OpenTelemetry Tracer Provider
provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'localhost:4317')))
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# Instrument pymemcache
PymemcacheInstrumentor().instrument()

# Use pymemcache as usual
# Ensure a memcached server is running at localhost:11211
try:
    client = Client(('localhost', 11211))
    client.set('my_key', 'my_value')
    value = client.get('my_key')
    print(f"Retrieved value: {value.decode('utf-8') if value else None}")
    client.delete('my_key')
except Exception as e:
    print(f"Error connecting to Memcached or during operation: {e}")
    print("Please ensure a memcached server is running at localhost:11211")

# Flush spans before exiting
provider.shutdown()

view raw JSON →