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 Manual instrumentation docs at https://opentelemetry.io/docs/instrumentation/python/manual/.

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 Manual instrumentation docs at https://opentelemetry.io/docs/instrumentation/python/manual/.

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.