OpenTelemetry Botocore Instrumentation

Instrument botocore and aiobotocore to trace service requests.

There are two options for instrumenting code. The first option is to use the opentelemetry-instrument executable which will automatically instrument your botocore or aiobotocore client. The second is to programmatically enable instrumentation via the following code:

Usage

from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
import botocore.session


# Instrument botocore
BotocoreInstrumentor().instrument()

# This will create a span with botocore-specific attributes
session = botocore.session.get_session()
session.set_credentials(
    access_key="access-key", secret_key="secret-key"
)
ec2 = session.create_client("ec2", region_name="us-west-2")
ec2.describe_instances()

Async Usage

from opentelemetry.instrumentation.botocore import AiobotocoreInstrumentor
import aiobotocore.session
import asyncio


async def main():
    # Instrument Aiobotocore
    AiobotocoreInstrumentor().instrument()

    # This will create a span with aiobotocore-specific attributes
    session = aiobotocore.session.get_session()
    async with session.create_client("ec2") as client:
        await client.describe_instances()

asyncio.run(main())

Thread Context Propagation

boto3’s S3 upload_file and download_file methods use background threads for multipart transfers. To ensure trace context is propagated to these threads, also enable the threading instrumentation:

from opentelemetry.instrumentation.threading import ThreadingInstrumentor
from opentelemetry.instrumentation.botocore import BotocoreInstrumentor

ThreadingInstrumentor().instrument()
BotocoreInstrumentor().instrument()

When using auto-instrumentation (opentelemetry-instrument), both instrumentors are enabled automatically if their packages are installed.

API

The instrument method (for both BotocoreInstrumentor and AiobotocoreInstrumentor) accepts the following keyword args:

tracer_provider (TracerProvider) - an optional tracer provider
request_hook (Callable[[Span, str, str, dict], None]) - a function with extra user-defined logic to be performed before performing the request
response_hook (Callable[[Span, str, str, dict], None]) - a function with extra user-defined logic to be performed after performing the request

for example:

from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
import botocore.session

def request_hook(span, service_name, operation_name, api_params):
    # request hook logic
    pass

def response_hook(span, service_name, operation_name, result):
    # response hook logic
    pass

# Instrument botocore with hooks
BotocoreInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook)

# This will create a span with botocore-specific attributes, including custom attributes added from the hooks
session = botocore.session.get_session()
session.set_credentials(
    access_key="access-key", secret_key="secret-key"
)
ec2 = session.create_client("ec2", region_name="us-west-2")
ec2.describe_instances()

class opentelemetry.instrumentation.botocore.BotocoreInstrumentor(*args, **kwargs)[source]

Bases: BaseInstrumentor

An instrumentor for Botocore.

See BaseInstrumentor

instrumentation_dependencies()[source]

Return a list of python packages with versions that the will be instrumented.

The format should be the same as used in requirements.txt or pyproject.toml.

For example, if an instrumentation instruments requests 1.x, this method should look like: :rtype: Collection[str]

def instrumentation_dependencies(self) -> Collection[str]:
return [‘requests ~= 1.0’]

This will ensure that the instrumentation will only be used when the specified library is present in the environment.

class opentelemetry.instrumentation.botocore.AiobotocoreInstrumentor(*args, **kwargs)[source]