This page guides you through the steps of configuring your BlackSheep application to work with Apitally. If you don’t have an account yet, now would be a good time to sign up.

Once you’re done with this guide, you will be able to:

  • Analyze requests to your application
  • Keep track of errors, response times and payload sizes
  • Understand how individual API consumers use your application
  • Log and inspect API requests and responses
  • Monitor your application’s uptime and receive alerts when it’s down
  • Set up custom alert rules and get notified when they’re triggered

​
Create app

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

Here you can also configure the environments (e.g. prod and dev) for your app, or simply accept the defaults.

Take a note of the client ID displayed after submitting. You will need it in the next step.

​
Add middleware

Next, install the Apitally SDK in your project with the extra.

pip install "apitally[blacksheep]"

Add the Apitally middleware to your BlackSheep application and provide the client_id for your app. You’ll find the client_id on the Setup instructions page for your app in the Apitally dashboard, which is displayed immediately after creating the app.

from blacksheep import Application
from apitally.blacksheep import use_apitally

app = Application()
use_apitally(
    app,
    client_id="your-client-id",
    env="dev",  # or "prod" etc.
)

Add the Apitally middleware before any other middleware to ensure it wraps the entire stack.

Deploy your application with these changes, or restart if you're testing locally.

At this point the basic setup for your application is complete and you will start seeing data in the Apitally dashboard. However, you won't be able to analyze API consumers yet.

​
Identify consumers

To analyze and filter API traffic by consumers, you can associate requests with consumer identifiers in your application.

In most cases, use the authenticated identity to identify the consumer. The identifier should be a string, such as a username, email address, or any other unique identifier.

Optionally, you can also provide a display name and group for each consumer.

To associate requests with consumers, provide a callback function that takes a Request object as an argument and returns a consumer identifier, an ApitallyConsumer object or None.

Alternatively, you can set the apitally_consumer claim on the request.identity object, for example in your authentication handler.

from blacksheep import Application, Request
from apitally.blacksheep import use_apitally

def get_consumer(request: Request) -> str | None:
    if request.identity.is_authenticated:
        return request.identity.sub
    return None

app = Application()
use_apitally(
    app,
    client_id="your-client-id",
    env="dev",  # or "prod" etc.
    consumer_callback=get_consumer,
)

Now the Consumers page in the Apitally dashboard shows you information about all consumers that have made requests to your application. You can also filter insights on other the dashboards by consumer and better understand how each of them use your application.

​
Configure request logging

Logging of individual requests and responses is disabled by default to protect potentially sensitive data. If you enable it, you can configure in detail what parts of the request and response should be logged. You can also mask sensitive information (e.g. in headers) and exclude certain requests from logging.

The SDK applies default masking rules for common sensitive headers, query parameters and request/response body fields.

from blacksheep import Application
from apitally.blacksheep import use_apitally

app = Application()
use_apitally(
    app,
    client_id="your-client-id",
    env="dev",  # or "prod" etc.
    enable_request_logging=True,
    log_request_headers=True,
    log_request_body=True,
    log_response_body=True,
)

This page guides you through the steps of configuring your BlackSheep application to work with Apitally. If you don’t have an account yet, now would be a good time to sign up.

Once you’re done with this guide, you will be able to:

  • Analyze requests to your application
  • Keep track of errors, response times and payload sizes
  • Understand how individual API consumers use your application
  • Log and inspect API requests and responses
  • Monitor your application’s uptime and receive alerts when it’s down
  • Set up custom alert rules and get notified when they’re triggered

​
Create app

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

Here you can also configure the environments (e.g. prod and dev) for your app, or simply accept the defaults.

Take a note of the client ID displayed after submitting. You will need it in the next step.

​
Add middleware

Next, install the Apitally SDK in your project with the extra.

pip install "apitally[blacksheep]"

Add the Apitally middleware to your BlackSheep application and provide the client_id for your app. You’ll find the client_id on the Setup instructions page for your app in the Apitally dashboard, which is displayed immediately after creating the app.

from blacksheep import Application
from apitally.blacksheep import use_apitally

app = Application()
use_apitally(
    app,
    client_id="your-client-id",
    env="dev",  # or "prod" etc.
)

Add the Apitally middleware before any other middleware to ensure it wraps the entire stack.

Deploy your application with these changes, or restart if you're testing locally.

At this point the basic setup for your application is complete and you will start seeing data in the Apitally dashboard. However, you won't be able to analyze API consumers yet.

​
Identify consumers

To analyze and filter API traffic by consumers, you can associate requests with consumer identifiers in your application.

In most cases, use the authenticated identity to identify the consumer. The identifier should be a string, such as a username, email address, or any other unique identifier.

Optionally, you can also provide a display name and group for each consumer.

To associate requests with consumers, provide a callback function that takes a Request object as an argument and returns a consumer identifier, an ApitallyConsumer object or None.

Alternatively, you can set the apitally_consumer claim on the request.identity object, for example in your authentication handler.

from blacksheep import Application, Request
from apitally.blacksheep import use_apitally

def get_consumer(request: Request) -> str | None:
    if request.identity.is_authenticated:
        return request.identity.sub
    return None

app = Application()
use_apitally(
    app,
    client_id="your-client-id",
    env="dev",  # or "prod" etc.
    consumer_callback=get_consumer,
)

Now the Consumers page in the Apitally dashboard shows you information about all consumers that have made requests to your application. You can also filter insights on other the dashboards by consumer and better understand how each of them use your application.

​
Configure request logging

Logging of individual requests and responses is disabled by default to protect potentially sensitive data. If you enable it, you can configure in detail what parts of the request and response should be logged. You can also mask sensitive information (e.g. in headers) and exclude certain requests from logging.

The SDK applies default masking rules for common sensitive headers, query parameters and request/response body fields.

from blacksheep import Application
from apitally.blacksheep import use_apitally

app = Application()
use_apitally(
    app,
    client_id="your-client-id",
    env="dev",  # or "prod" etc.
    enable_request_logging=True,
    log_request_headers=True,
    log_request_body=True,
    log_response_body=True,
)