Docs » Instrument back-end applications to send spans to Splunk APM » Instrument Python applications for Splunk Observability Cloud » Manually instrument Python applications for Splunk Observability Cloud

Manually instrument Python applications for Splunk Observability Cloud πŸ”—

Instrumenting applications automatically using the agent of the Splunk Distribution of OpenTelemetry Python covers most needs. Manually instrumenting your application is only necessary when, for example, you need to add custom attributes to spans or need to manually generate spans.

Create custom traces πŸ”—

To create custom spans and traces, follow these steps:

  1. If you can’t use the splunk-py-trace command, import and configure start_tracing:

    from splunk_otel.tracing import start_tracing
    
    start_tracing()
    
    # Also accepts optional settings. For example:
    #
    # start_tracing(
    #   service_name='<my-python-service>',
    #   span_exporter_factories=[OTLPSpanExporter]
    #   access_token='<access_token>',
    #   max_attr_length=12000,
    #   trace_response_header_enabled=True,
    #   resource_attributes={
    #    'service.version': '<your_version>',
    #    'deployment.environment': '<your_environment>',
    #  })
    

    As an alternative, you can also import the OpenTelemetry SDK:

    from opentelemetry import trace
    from opentelemetry.sdk.trace import TracerProvider
    from opentelemetry.sdk.trace.export import (
       BatchSpanProcessor,
       ConsoleSpanExporter,
    )
    
  2. Create a tracer for your spans:

    provider = TracerProvider()
    processor = BatchSpanProcessor(ConsoleSpanExporter())
    provider.add_span_processor(processor)
    
    trace.set_tracer_provider(provider)
    tracer = trace.get_tracer("tracer.name")
    
  3. Create a span as current span:

    def reticulate_splines():
       with tracer.start_as_current_span("span-name") as span:
          print("Reticulating splines...")
          # When the 'with' block goes out of scope, the 'span' is closed
    

For more examples, see the OpenTelemetry official documentation .

Create custom metrics πŸ”—

The Splunk Distribution of OpenTelemetry Python supports the following instrumentations:

  • Counter (synchronous)

  • Counter (asynchronous)

  • Gauge (asynchronous)

  • UpDownCounter (synchronous)

  • UpDownCounter (asynchronous)

To create custom metrics, follow the steps depending on the type of metric instrumentation.

Synchronous instruments, like counters, are invoked inline with business logic. An example of synchronous instrument is a counter for the number of bytes sent to a server. They support context propagation.

  1. Import the OpenTelemetry API:

    from opentelemetry import metrics
    from opentelemetry.sdk.metrics import MeterProvider
    from opentelemetry.sdk.metrics.export import (
       ConsoleMetricExporter,
       PeriodicExportingMetricReader,
    )
    
  2. Create a meter provider:

    meter := otel.Meter("ExampleService")
    
  3. Create an instrument to take measurements:

    metric_reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
    provider = MeterProvider(metric_readers=[metric_reader])
    
    metrics.set_meter_provider(provider)
    meter = metrics.get_meter("my.meter.name")
    
  4. Perform the measurements:

    peanut_counter = meter.create_counter(
       "peanut.counter", unit="1", description="Counts the number of consumed peanuts"
    )
    
    def do_stuff(work_item):
       peanut_counter.add(1, {"work.type": work_item.work_type})
       print("Collecting peanuts...")
    

For more examples, see the OpenTelemetry official documentation .

Frameworks that require manual instrumentation πŸ”—

Some Python frameworks only support manual instrumentation. For specific instructions, see:

Note

Manual OTel instrumentation is fully compatible with Splunk automatic Python instrumentation and is fully supported by Splunk.