Installing the package

pip install opentelemetry-instrumentation-digma

Instrumenting an existing project

If you are introducing both OTEL and Digma

To make it convenient to get started quickly with some default for both OpenTelemetry and Digma, a quick bootsrap function is provided. This is not intended for usage if you already have OpenTelmetry set up in your project, nor be used as a production configuration.

from opentelemetry.instrumentation.digma import digma_opentelemetry_boostrap

digma_opentelemetry_boostrap(service_name='server-name', digma_backend="http://localhost:5050",
                             configuration=DigmaConfiguration().trace_this_package())

If you are already using OpenTelemtry tracing in your project

If you have an existing OpenTelemtry instrumentaiton set up, simply use the DigmaConfiguration object to create a Resource object and merge it with your resource to import all of the needed attributes.

resource = Resource.create(attributes={SERVICE_NAME: service_name})
resource = resource.merge(DigmaConfiguration().trace_this_package())

You can use a standard OTLP exporter to the Digma collector for local deployments:

exporter = OTLPSpanExporter(endpoint="localhost:5050", insecure=True)
provider.add_span_processor(BatchSpanProcessor(exporter))

Alternatively, if you're already using a collector component you can simply modify its configuration file:

exporters:
...
otlp/digma:
    endpoint: "localhost:5050"
    tls:
      insecure: true
service:
  pipelines:
    traces:
      exporters: [otlp/digma, ...]

Building the package from source

python -m build

The Digma instrumentation helper configuration options

The tracing decorator

The digma package include an optional tracing decorator intended to make span declarations easier and less repetitive. You can use the decorator at the function or class level to specify a span should be automatically created.

The decorator will automatically add additional context for each span based on the wrapped method.

Example usage:

@instrument
def standalone_function(self):
    # Will create a span named 'standalone_function' (default naming)
    pass
    
@instrument(attributes={"one": "two"})
class SomeClass:

    @instrument(span_name="function_decorator", attributes={"two": "three"})
    def function_one(self):
        # Will create a span named 'function_decorator' with above attributes
        pass

    def function_two(self):
        # Will create a span named 'function_two', since SomeClass has decorator
        pass
   
    def _function_three(self):
        # Will not create a span for this function as it is private
        pass

    @instrument(ignore=True)
    def do_not_instrument(self):
        # Will not create a span for this function as it is set to ignore
        pass