Registry /
observability / opentelemetry-instrumentation-click
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.6s · import 0.000s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ClickInstrumentor
✓ from opentelemetry.instrumentation.click import ClickInstrumentor
✗ from opentelemetry.instrumentation.click import ClickInstrumentor
This quickstart demonstrates how to instrument a basic Click application. It sets up a `TracerProvider` with a `ConsoleSpanExporter` for demonstration, then initializes `ClickInstrumentor` to automatically trace Click commands. Manual spans are added within commands for finer-grained tracing.
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.click import ClickInstrumentor
import click
import os
# 1. Configure OpenTelemetry TracerProvider and Exporter
# In a real application, you would typically use an OTLPSpanExporter
# pointing to an OpenTelemetry Collector or an observability backend.
resource = Resource.create({"service.name": "my-click-cli"})
provider = TracerProvider(resource=resource)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(span_processor)
trace.set_tracer_provider(provider)
# 2. Instrument Click
ClickInstrumentor().instrument()
# 3. Define a Click application
@click.group()
def cli():
"""A simple CLI application."""
pass
@cli.command()
@click.option('--name', default='World', help='Name to greet.')
def hello(name):
"""Greets the user."""
# Manual span creation to show how to add more detail
with trace.get_current_tracer().start_as_current_span("say-hello-command"):
click.echo(f"Hello, {name}!")
@cli.command()
@click.argument('num', type=int)
def square(num):
"""Calculates the square of a number."""
with trace.get_current_tracer().start_as_current_span("calculate-square-command"):
result = num * num
click.echo(f"The square of {num} is {result}")
if __name__ == '__main__':
# To run this example:
# 1. Save the code as `app.py`.
# 2. Execute from your terminal:
# python app.py hello --name OpenTelemetry
# python app.py square 7
cli()
Debug
Known issues
gotchaThis instrumentation library is currently in beta (`0.62b0`). While functional, it may introduce breaking changes in future minor or patch versions before reaching a stable 1.0 release.fixReview release notes for each new version to identify any breaking changes or updated APIs.
affects: All versions below 1.0.0
gotchaFor the Click instrumentation to generate telemetry, you must have `opentelemetry-api` and `opentelemetry-sdk` installed alongside `opentelemetry-instrumentation-click`. The `click` library itself must also be installed in your environment.fixEnsure all required OpenTelemetry core packages and the `click` library are installed: `pip install opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-click click`.
affects: All versions
gotchaIn CLI applications, especially those with multiple subcommands or long-running tasks, proper context propagation can be challenging. While the instrumentation provides basic tracing, complex scenarios might require manual intervention to ensure trace context correctly flows across different parts of your Click application or to other services.fixFor complex flows, consider explicitly passing context objects or using `opentelemetry.context` utilities to manage and propagate trace context manually.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
clickrequiredThe library instruments Click applications.
opentelemetry-apirequiredCore OpenTelemetry API for defining telemetry.
opentelemetry-sdkrequiredCore OpenTelemetry SDK for processing and exporting telemetry.
opentelemetry-instrumentationrequiredBase package for OpenTelemetry Python instrumentations.