{"id":4154,"library":"opentelemetry-instrumentation-click","title":"OpenTelemetry Click Instrumentation","description":"This library provides automatic instrumentation for applications built with the Click framework, allowing them to emit traces and spans compatible with the OpenTelemetry specification. It is part of the `opentelemetry-python-contrib` repository, currently in beta version 0.62b0, and receives frequent updates alongside other contributed instrumentations.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","instrumentation","click","tracing","cli","observability","python"],"install":[{"cmd":"pip install opentelemetry-instrumentation-click","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"The library instruments Click applications.","package":"click"},{"reason":"Core OpenTelemetry API for defining telemetry.","package":"opentelemetry-api"},{"reason":"Core OpenTelemetry SDK for processing and exporting telemetry.","package":"opentelemetry-sdk"},{"reason":"Base package for OpenTelemetry Python instrumentations.","package":"opentelemetry-instrumentation"}],"imports":[{"symbol":"ClickInstrumentor","correct":"from opentelemetry.instrumentation.click import ClickInstrumentor"}],"quickstart":{"code":"from opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.click import ClickInstrumentor\nimport click\nimport os\n\n# 1. Configure OpenTelemetry TracerProvider and Exporter\n# In a real application, you would typically use an OTLPSpanExporter\n# pointing to an OpenTelemetry Collector or an observability backend.\nresource = Resource.create({\"service.name\": \"my-click-cli\"})\nprovider = TracerProvider(resource=resource)\nspan_processor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(span_processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument Click\nClickInstrumentor().instrument()\n\n# 3. Define a Click application\n@click.group()\ndef cli():\n    \"\"\"A simple CLI application.\"\"\"\n    pass\n\n@cli.command()\n@click.option('--name', default='World', help='Name to greet.')\ndef hello(name):\n    \"\"\"Greets the user.\"\"\"\n    # Manual span creation to show how to add more detail\n    with trace.get_current_tracer().start_as_current_span(\"say-hello-command\"):\n        click.echo(f\"Hello, {name}!\")\n\n@cli.command()\n@click.argument('num', type=int)\ndef square(num):\n    \"\"\"Calculates the square of a number.\"\"\"\n    with trace.get_current_tracer().start_as_current_span(\"calculate-square-command\"):\n        result = num * num\n        click.echo(f\"The square of {num} is {result}\")\n\nif __name__ == '__main__':\n    # To run this example:\n    # 1. Save the code as `app.py`.\n    # 2. Execute from your terminal:\n    #    python app.py hello --name OpenTelemetry\n    #    python app.py square 7\n    cli()","lang":"python","description":"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."},"warnings":[{"fix":"Review release notes for each new version to identify any breaking changes or updated APIs.","message":"This 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.","severity":"gotcha","affected_versions":"All versions below 1.0.0"},{"fix":"Ensure all required OpenTelemetry core packages and the `click` library are installed: `pip install opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-click click`.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For complex flows, consider explicitly passing context objects or using `opentelemetry.context` utilities to manage and propagate trace context manually.","message":"In 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}