Setup guide for Starlette

This setup guide is for v1 of the Python SDK (currently in beta).

This page guides you through the setup of the Apitally SDK for your Starlette application. If you don’t have an Apitally account yet, sign up before getting started. Once you’re done with this guide, you will be able to:

Get detailed metrics on API usage, errors, and performance
Track API adoption and usage by individual consumers
Log individual API requests, responses, and correlated application logs
See what’s causing slow API requests with traces
Monitor uptime and set up custom alerts

Requirements

Requires Python 3.10+ and Starlette 0.29+.

Create app

To get started, create a new app in the Apitally dashboard and select Starlette as your framework. Create app

You can also configure the environments (e.g. prod and dev) for your app, or simply accept the defaults. After submitting, you will see tailored setup instructions for your app. These include your write token and code snippets you can copy and paste into your project.

The write token (apt_...) provided in the setup instructions uniquely identifies your app for the purpose of data ingestion only. It does not grant any kind of read access to your data.

Install the SDK

Install the Apitally SDK with the starlette extra as a dependency in your project.

pip install --pre "apitally[starlette]"

uv add --prerelease allow "apitally[starlette]"

poetry add --allow-prereleases "apitally[starlette]"

Initialize Apitally

Call apitally.init with your Starlette application, the write token, and other configuration options immediately after creating the app.

import apitally
from starlette.applications import Starlette

app = Starlette()

apitally.init(
    app,
    write_token="your-write-token",
    env="dev",  # or "prod" etc.
)

You can also set the APITALLY_WRITE_TOKEN and APITALLY_ENV environment variables instead of passing write_token and env in code. Deploy your application with these changes, or restart it if you’re testing locally.

The basic setup is now complete. Metrics and logs will start appearing in the Apitally dashboard.

Identify consumers

Consumers are the users or applications calling your API. Identifying them lets you analyze and filter API traffic by consumer in Apitally. Call apitally.set_consumer during request handling to associate the current request with a consumer identifier. You can call it wherever the consumer is known, such as in an endpoint, existing middleware, or authentication code. You can also provide a display name and group for each consumer. These examples use request.user, which is provided by Starlette’s authentication middleware.

import apitally
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route


async def list_items(request: Request) -> JSONResponse:
    if request.user.is_authenticated:
        apitally.set_consumer(
            request.user.identity,
            name=request.user.display_name,  # optional
            group="Customers",  # optional
        )
    return JSONResponse(["item1"])


app = Starlette(routes=[Route("/items", list_items)])
apitally.init(app, write_token="your-write-token")

import apitally
from starlette.applications import Starlette
from starlette.requests import Request


def identify_consumer(app):
    async def middleware(scope, receive, send):
        if scope["type"] == "http":
            request = Request(scope)
            if request.user.is_authenticated:
                apitally.set_consumer(
                    request.user.identity,
                    name=request.user.display_name,  # optional
                    group="Customers",  # optional
                )
        await app(scope, receive, send)

    return middleware


app = Starlette()
apitally.init(app, write_token="your-write-token")
app.add_middleware(identify_consumer)

Capture headers and bodies

Only response headers are captured by default. You can opt in to capture request headers as well as request and response bodies when initializing Apitally.

apitally.init(
    app,
    write_token="your-write-token",
    env="dev",  # or "prod" etc.
    capture_request_headers=True,
    capture_request_body=True,
    capture_response_body=True,
)

Mask sensitive information

The SDK automatically masks common sensitive query parameters, headers, and body fields. To mask additional data, pass regular expressions matching query parameter names, header names, or body field names to mask_query_params, mask_headers, or mask_body_fields, respectively. Matching is case-insensitive.

apitally.init(
    app,
    write_token="your-write-token",
    mask_query_params=[r"^account_id$"],
    mask_headers=[r"^X-Custom-Key$"],
    mask_body_fields=[r"^credit_card$"],
)

You can use the mask_request_body and mask_response_body callbacks to mask individual fields or entire bodies using custom logic. Use mask_log_record to mask or drop application log records. More information about masking is available here.

Sample requests

If your application receives a lot of traffic, you may want to sample requests to stay within your request logs quota. Metrics will continue to count every request regardless of sampling. Use sample_rate to capture logs and traces for a fraction of requests.

apitally.init(
    app,
    write_token="your-write-token",
    sample_rate=0.1,  # capture logs and traces for 10% of requests
)

You can also use the sample_on_request and sample_on_response callbacks to make sampling decisions using custom logic. More information about sampling is available here.

Instrument third-party libraries

Instrumenting third-party libraries adds details about database queries, HTTP calls to external services, and other operations to your request traces. This lets you see how these operations contribute to API response times. The SDK provides helper functions in apitally.otel to instrument popular libraries. Each requires a separate OpenTelemetry instrumentation package. For example, to trace database queries made with SQLAlchemy, install opentelemetry-instrumentation-sqlalchemy:

pip install opentelemetry-instrumentation-sqlalchemy

uv add opentelemetry-instrumentation-sqlalchemy

poetry add opentelemetry-instrumentation-sqlalchemy

Then call instrument_sqlalchemy with your SQLAlchemy engine at application startup:

from apitally.otel import instrument_sqlalchemy

instrument_sqlalchemy(engine)

More information about tracing and the provided instrumentation helpers is available here.

SDK reference

Setup guides

Setup guide for Starlette

Requirements

Create app

Install the SDK

Initialize Apitally

Identify consumers

Capture headers and bodies

Mask sensitive information

Sample requests

Instrument third-party libraries

​Requirements

​Create app

​Install the SDK

​Initialize Apitally

​Identify consumers

​Capture headers and bodies

​Mask sensitive information

​Sample requests

​Instrument third-party libraries

Requirements

Create app

Install the SDK

Initialize Apitally

Identify consumers

Capture headers and bodies

Mask sensitive information

Sample requests

Instrument third-party libraries