DEV Community: Apitally

Getting started with logging in FastAPI

Simon Gurcke — Mon, 03 Nov 2025 10:41:24 +0000

Logging is critical for understanding and debugging FastAPI apps in production. When things go wrong, logs are usually the best starting point for any investigation.

For APIs, logging can be broken down into two categories: request logs, which record individual API requests and responses, and application logs, which contain detailed messages from your application's code. Ideally, both types of logs are correlated, meaning each log record is linked to the API request.

In this article, we'll cover the basics of logging and log correlation in FastAPI. We'll also introduce Apitally as a simple solution for capturing request logs and correlated application logs with minimal effort.

Basic request logging

Request logs are a chronological record of every API request your application handles. A typical entry contains at least a timestamp, the HTTP method, request path, and response status code.

If you're using uvicorn to run your FastAPI app, you actually get basic request logs in your console out of the box. However, these don't include timestamps or correlation IDs, which are necessary to link other log messages with requests.

We can address these shortcomings with a custom logging middleware. That way we'll have more control over what is included in the logs. For example, we could add the response time to identify slow requests.

Let's implement this in a simple FastAPI app:

import logging
import time
from fastapi import FastAPI, Request

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
)
logger = logging.getLogger(__name__)

app = FastAPI(title="Example API")

@app.middleware("http")
async def log_requests(request: Request, call_next):
    start_time = time.perf_counter()
    response = await call_next(request)
    response_time = time.perf_counter() - start_time
    logger.info(f"{request.method} {request.url.path} {response.status_code} {response_time:.3f}s")
    return response

@app.get("/hello")
async def say_hello():
    logger.info("Saying hello")
    return {"message": "Hello!"}

Note: You can disable uvicorn's built-in logs with the --no-access-logs option.

The middleware logs request details after the route handler returns, while the route handler also logs during its execution. When two requests are processed concurrently, the log output could look like this:

2025-09-30 14:29:00,123 [main] INFO: Saying hello
2025-09-30 14:29:00,123 [main] INFO: Saying hello
2025-09-30 14:29:00,124 [main] INFO: GET /hello 200 0.001s
2025-09-30 14:29:00,124 [main] INFO: GET /hello 200 0.001s

As you can see there is no way to tell which "Saying hello" message belongs to which request. Not a big deal in this simple example, but essential when debugging production issues, especially with high request volumes.

Log correlation

To link log messages with requests we need a correlation ID. I highly recommend using the asgi-correlation-id package for this purpose.

pip install asgi-correlation-id

The package provides a middleware we can add to our application. It automatically generates a correlation ID for each incoming request. Additionally, we need to configure a log filter and include the correlation ID in our log format. This can't be done using basicConfig, so we need to use the more verbose dictConfig instead.

import logging
from asgi_correlation_id import CorrelationIdMiddleware
from fastapi import FastAPI

logging.config.dictConfig({
    "version": 1,
    "disable_existing_loggers": False,
    "filters": {
        "correlation_id": {
            "()": "asgi_correlation_id.CorrelationIdFilter",
            "uuid_length": 32,
            "default_value": "-",
        },
    },
    "formatters": {
        "standard": {
            "format": "%(asctime)s [%(correlation_id)s] [%(name)s] %(levelname)s: %(message)s",
        },
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "filters": ["correlation_id"],
            "formatter": "standard",
        },
    },
    "root": {
        "level": "INFO",
        "handlers": ["console"],
    },
})
logger = logging.getLogger(__name__)

app = FastAPI()
app.add_middleware(CorrelationIdMiddleware)

# ...

If we made two concurrent requests to our API again, we'd get the following output. You can see how the correlation IDs allow us to tell which messages belong together.

2025-09-30 14:36:00,123 [main] [50e2646d5e594cb197ae9f3d21de7a57] INFO: Saying hello
2025-09-30 14:36:00,123 [main] [e986f5451c4b4e0fb7fea90dda32608f] INFO: Saying hello
2025-09-30 14:36:00,124 [main] [50e2646d5e594cb197ae9f3d21de7a57] INFO: GET /hello 200 0.001s
2025-09-30 14:36:00,124 [main] [e986f5451c4b4e0fb7fea90dda32608f] INFO: GET /hello 200 0.001s

Beyond log files

We now have correlated logs being written to the console or log files. That's a big step up. But if you've ever tried to debug a production issue by sifting through large log files, you know this approach doesn't scale. For many APIs, the volume of logs can quickly become too large to inspect manually.

On top of that, request and response metadata from logs often isn't enough. You may need to inspect the full request and response headers and payloads to get to the bottom of an issue. These are impractical to capture in log files.

Introducing Apitally

Apitally is designed to solve these exact challenges. It provides a user-friendly and searchable interface for request logs and automatically handles log correlation. You can configure exactly what gets logged, including headers and payloads, while masking rules make it easy to avoid capturing sensitive information.

To get started, let's install the Apitally SDK for FastAPI.

pip install "apitally[fastapi]"

Then, add the Apitally middleware to your FastAPI app. This replaces the need for asgi-correlation-id and any custom middleware for request logging.

from fastapi import FastAPI
from apitally.fastapi import ApitallyMiddleware

app = FastAPI()
app.add_middleware(
    ApitallyMiddleware,
    client_id="your-client-id",
    env="dev",  # or "prod" etc.
    enable_request_logging=True,
    capture_logs=True,

    # Configure what's included in logs
    log_request_headers=True,
    log_request_body=True,
    log_response_body=True,

    # Mask headers or body fields using regex
    mask_headers=[r"^X-Sensitive-Header$"],
    mask_body_fields=[r"^sensitive_field$"],
)

Check out this reference for all available parameters and default masking patterns.

With this configuration, the Apitally SDK automatically captures request and application logs, stores them in a temporary file, and periodically flushes them to Apitally's servers. All this happens asynchronously to not affect your app's performance.

You can then find and inspect the logs in the Apitally dashboard, with various filtering options. For example, you can filter by:

Consumer or client IP address
HTTP method, request URL or response status code
Request and response body (free text search)
Response time (find slow requests)

Clicking on a request in the logs brings up a modal with rich details, including:

Path and query parameters
Headers (with sensitive headers masked automatically)
Request and response bodies (supports text and JSON up to 50 KB)
Correlated application logs
List of related requests from same client

Apitally stores log data in a ClickHouse database hosted in the US and retains it for 15 days. Log volume limits apply based on the pricing tier, with the lowest tier allowing 1 million requests per month. The highest tier includes 25 million requests and users can enable usage-based pricing to go beyond that limit.

Conclusion

With request logging and correlation IDs in place, we can trace through our logs effectively when troubleshooting issues. Our custom middleware and the asgi-correlation-id package provided a straightforward way to implement this in FastAPI.

When logs are written only to the console or files, searching and filtering can become inefficient as the volume grows. Apitally solves this by indexing log data, making it easy to find and inspect requests, responses, and related log messages. Its SDK for FastAPI automates the entire logging pipeline and is ready for production with minimal configuration.

What makes a good REST API?

Simon Gurcke — Thu, 16 May 2024 05:59:04 +0000

Today, anyone with basic programming skills can build an API.
Frameworks like FastAPI, which provide an intuitive interface and are well documented, make it really easy.
But what does it take to ship and maintain a robust REST API that other developers love using, that always works as expected and scales well?

This article offers an opinionated overview of REST API best practices covering:

API design
OpenAPI
Validation
Rate limiting
Asynchronous processing
Monitoring

I won’t go into too much detail in each section, but instead I’ll link to further resources on the topic for those that are interested to go deeper.

API design: Follow best practices

A good API has a well thought out and logical design of endpoints, returns data in a manner that is easy to consume, and provides detailed feedback in case of errors.

There are established best practices for designing API endpoints. These typically include:

Use plural nouns for resource collections in URIs, e.g. /v1/posts/123
Avoid using verbs in the endpoint URIs, use an appropriate HTTP method instead
Keep all characters in the URI lowercase, using hyphens to separate words
Logically nest endpoints to show relationships. For example, a comment on a blog post should be /v1/posts/{postId}/comments/{commentId}.
Include a version in the endpoint URIs, like /v1/posts, to allow for future updates without breaking existing clients
Ensure that naming conventions, response formats, and behavior are consistent across all API endpoints
Use appropriate HTTP status codes in responses, e.g. 201 Created if a new resource was created or 403 Forbidden for an authorization error
Allow users to filter, sort and paginate through datasets using query parameters and avoid returning excessively large API responses

Further resources:

Best practices for REST API design - Stack Overflow Blog
RESTful API Guidelines - Zalando
API Design Standard - Australian Government

OpenAPI: Auto-generate documentation and SDKs

A good API has a complete OpenAPI specification that acts as a contract between the API provider and consumers. It is also used to create comprehensive documentation and SDKs.

Many web frameworks offer support for auto-generating an OpenAPI specification from endpoint definitions in the API's codebase, either out of the box or via third-party libraries.
You can use annotations to add additional details such as descriptions and examples.
Keeping a single source of truth through a tight integration with the web framework helps keep the specification up-to-date and version-controlled alongside the codebase.

There are many tools that use the OpenAPI specification to:

Generate interactive documentation
Generate client libraries / SDKs in various languages
Generate mock servers for testing
Automatically test your API endpoints against the specification
And more ...

Further resources:

What is OpenAPI? - OpenAPI Initiative
The OpenAPI Specification Explained - OpenAPI Initiative
OpenAPI.Tools - APIs You Won't Hate

Recommended tools:

Redoc: Generate API documentation
Mintlify: Generate API documentation
openapi-ts: Generate API client for TypeScript
openapi-python-client: Generate API client for Python

Validation

A good API meticulously validates user input and provides detailed and structured error messages when invalid input is received.

Being a fundamental task, input validation is supported well by many web frameworks.
FastAPI, for example, uses pydantic for this purpose, and automatically generates responses with well-structured details about validation errors (see example below).

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": { ... }
     }
  ]
}

When creating validation rules, consider the following criteria:

Type: Ensure input has the correct data type.
Length: Check that the input has the expected length and define an upper limit (e.g. forbid extremely long string input, or arrays with millions of elements).
Format: Check string inputs against expected patterns to ensure they are formatted correctly (e.g. dates).
Range: Ensure that numeric values fall within the accepted range.
Business logic: Check input against your own business rules (do this last).

Input validation should occur as early as possible and fail fast when handling invalid requests.
Use an appropriate HTTP status code in the 4xx range for validation errors (e.g. 400 Bad Request).

Some web frameworks can also perform validation of API responses (e.g. FastAPI with pydantic), guaranteeing that the returned data always has the correct structure and type.
Alternatively, the API endpoints should be covered by automated tests that ensure the response data is formatted correctly (according to the API’s specification) under all circumstances.

Further resources:

Input Validation Cheat Sheet - OWASP

Rate limiting

A good API employs rate limiting to prevent overloading and ensure quality of service for all clients.

Rate limiting can be implemented at different levels of your stack, including the network level, the web server, your application code, or a combination of these.

As a first layer of protection, most web servers can be easily configured to rate limit requests by IP address.
For more flexibility and better control, you might want to implement (additional) rate limiting logic in the application layer.
For example, you could apply dynamic limits based on the users’ pricing tier.

When rejecting requests due to rate limiting, it is good practice to use the 429 Too Many Requests response status code and include headers such as Retry-After to give clients feedback they can use to handle the rate limit gracefully.

Ensure your API documentation clearly states rate limiting rules and describes the rate limiting headers used.

Further resources:

API Rate Limiting - Everything You Need to Know - HubSpot Blog
API Rate Limiting: The Ultimate Guide - Kinsta Knowledge Base

Asynchronous processing

A good API performs longer running tasks in the background using a task queue and worker system and avoids keeping client connections open for extended periods.

This typically involves accepting a task from a client, adding it to the task queue, and then immediately sending a response back acknowledging that the task was received and is being processed.
The 202 Accepted response status code is often used in this scenario.

This approach improves user experience and helps prevent timeouts as the client isn't left waiting for a response.
It also allows the server to handle multiple requests concurrently and remain responsive while processing long-running tasks.

APIs should also provide a way for clients to check the status of their tasks and fetch the result, if applicable.
This could be implemented as separate endpoints which the client can poll at intervals.

Further resources:

Asynchronous Request-Reply pattern - Microsoft Learn

Monitoring

A good API is proactively monitored to ensure its consistent availability, reliability and performance.

Having monitoring tools in place allows you to detect and respond to issues quickly, ideally before they impact users.
It also helps you understand how the API is being used and empowers you to make data-driven product and engineering decisions.

Monitoring should cover at least the following key aspects:

Traffic: Number of requests (per minute)
Errors: Failed requests due to client or server errors
Response times / latencies: How long it takes API endpoints to return a response
Uptime: Whether the API is available to consumers

Further resources:

4 facets of API monitoring you should implement - Apitally Blog

Recommended tools:

Apitally: Easy-to-use API monitoring for Python and Node.js

Discussion

Is there anything else that you think is an important best practice for REST APIs? Please leave a comment!

4 facets of API monitoring you should implement

Simon Gurcke — Sat, 02 Mar 2024 12:37:23 +0000

Introduction

Issues with APIs often have the potential to cause major disruptions to businesses. Proactive API monitoring is therefore essential for tech professionals who are responsible for maintaining the integrity and performance of business-critical APIs.

In this blog post we'll take an in-depth look at the four fundamental aspects of API monitoring every tech professional should consider to implement:

API traffic monitoring
API performance monitoring
API error monitoring
API uptime monitoring

Having these in place can empower teams to preemptively address potential issues, optimize API performance, make data-driven product and engineering decisions and ultimately deliver a seamless experience to end-users.

API traffic monitoring

This aspect of API monitoring involves tracking the volume and type of requests an API receives. It allows developers and product owners to understand how their APIs are being utilized in real-world scenarios, enabling them to make informed decisions about product development and enhancements. If the APIs are being used for integration with other internal systems, analyzing API traffic sheds light onto the behaviors of these systems and can reveal issues or opportunities for optimization.

An equally important benefit of API traffic monitoring is the ability to detect anomalies in usage patterns. Sudden spikes or drops in traffic to certain endpoints can indicate underlying issues, including malicious activities aiming to compromise the API. By setting up alerts for such irregularities, teams can quickly investigate and address the underlying causes, minimizing the risk of downtime or security breaches.

In essence, API traffic monitoring is not just about keeping tabs on the volume of requests; it's about leveraging data to drive strategic decisions, enhance user experiences, and maintain the robustness and integrity of APIs.

API performance monitoring

Performance is often a key differentiator for APIs. Fast response times not only enhance user experience but also increase the overall efficiency of applications that rely on your API. API performance monitoring involves measuring the time it takes for an API to respond to requests. This is done for the API as a whole, as well as for individual endpoints.

By tracking these latencies over time, you can identify trends and patterns, such as endpoints that consistently take longer to respond. This can help you pinpoint performance bottlenecks and optimize your API for better responsiveness.

Setting performance benchmarks based on these metrics is also crucial. They serve as a standard against which the API's ongoing performance can be measured. Any deviations from these benchmarks should trigger alerts to the API team to investigate and rectify potential issues. Thus, effective API performance monitoring leads to a faster, more reliable API and a smoother user experience.

API error monitoring

When talking about errors in the context of APIs, it makes sense to distinguish two different categories: server errors (5xx responses) and client errors (4xx responses).

Server errors

Server errors result from issues in your application or infrastructure. When API consumers hit server errors, all they can do is retry the request. Server errors can be temporary, for example, when there are intermittent networking issues within your stack. However, when a bug in your application consistently prevents certain requests from being handled successfully, there is nothing API consumers can do but to wait for you to fix the underlying issue. This is why it is vitally important that you have the right tools in place to alert you when these types of errors occur.

Client errors

Client errors are typically part of the API's regular operation. Monitoring these can provide valuable insights and identify ways to enhance the API's usability for end users. A sudden increase in client errors could indicate problems with your API, such as a new validation rule being too restrictive, or reveal issues with consumer systems providing malformatted input to the API.

In essence, API error monitoring not only helps in pinpointing and fixing issues within the API but also aids in understanding the end-user's interaction with the system. By effectively tracking and analyzing both server and client errors, teams can create a more reliable and user-friendly API.

API uptime monitoring

Uptime monitoring is another critical facet of API Monitoring. It refers to the act of ensuring that your API is available and functional at all times. Any downtime can lead to significant disruptions to connected systems, making uptime monitoring a crucial part of maintaining a high-quality user experience.

API uptime monitoring involves checking the availability of your API at regular intervals. This can be done by sending requests to various endpoints and verifying the responses. In addition to simple availability checks, uptime monitoring could also consider the 'health' of the response. This might involve checking that the response time is within acceptable limits, or that the data returned in the response is as expected.

Setting up robust alerting is another key aspect of uptime monitoring. Teams should be immediately notified when the API is down or experiencing problems. This allows them to quickly identify and rectify the issues, minimizing the impact on users.

In essence, API uptime monitoring ensures that your API is consistently ready and accessible, providing the high-quality, reliable service that your users expect.

Conclusion

In conclusion, effective API monitoring involves a comprehensive approach that takes into account API traffic, performance, errors, and uptime.

Fortunately, the technological landscape is filled with tools to assist in these areas. We've gathered some of them in the list below as a starting point for your own research. They range from simple and easy to implement to comprehensive and complex, catering to different use cases.

Recommended tools

Apitally: Simple and easy-to-use API monitoring tool covering traffic, performance, errors, and uptime.
Sentry: Error monitoring for applications, including APIs. Also offers application performance monitoring (APM).
Postman Uptime and performance monitoring for APIs.
Datadog: Comprehensive monitoring platform.
New Relic: Another comprehensive monitoring platform.
Prometheus: Open-source monitoring system. Often used together with Grafana.

FastAPI application monitoring made easy

Simon Gurcke — Sat, 06 Jan 2024 13:05:52 +0000

Let's assume your team has just shipped a new REST API using FastAPI. Now that it's live you want to know how it's being used and how it's performing. You may have questions like:

Is the API working as expected?
How many requests is the API handling, by how many unique consumers?
Which features of the API are being used the most, and by whom?
Are there any errors faced by consumers, and what types of errors?
What does the performance look like?
Is the API up & available to users at all times?

Out of the box, FastAPI doesn't provide any means for you to answer those kinds of questions. And it shouldn't. It's a web framework, not a monitoring solution, after all. There's many different ways to approach this, but let's dive into a couple of options.

The hard way

You might find recommendations on the internet for setting up Prometheus and Grafana to monitor your application. These are widely adopted open-source tools for monitoring all sorts of things, and they can certainly help you achieve what you're after.

This approach can be powerful and versatile, allowing you to implement things like custom metrics and infrastructure monitoring all within the same platform while tailoring everything exactly to your needs.

However, Prometheus and Grafana aren't exactly plug-and-play solutions. If you're new to them, you might need to invest a fair bit of time to get the answers you're looking for. You'll need to deploy and configure both tools, implement metrics logging using the Prometheus client in your application and then build dashboards in Grafana. Also, remember to consider the ongoing costs of hosting and maintaining these tools.

You may have good reasons for going down this path, and if you do, I highly recommend this article to get you started. On the other hand, if you'd prefer a simpler approach, read on.

The easy way

By using a purpose-built API monitoring solution, such as Apitally, you can gain insights into how your API is being used and how it's performing within a matter of minutes. This is possible because Apitally provides seamless integration with FastAPI via a simple middleware that captures relevant metadata about all handled requests and responses. This includes:

HTTP method and path of requests
Response status codes
Response times / latencies
Consumer identifiers (if configured)

This data syncs from your application to Apitally every minute and is then available for analysis on an intuitive dashboard that allows you to easily keep track of API requests, error rates and response times and provides insights into the usage and performance of each endpoint.

All you need to do is install a small dependency and add a couple of lines of code to your project, as shown in the example below.

from fastapi import FastAPI
from apitally.fastapi import ApitallyMiddleware

app = FastAPI()
app.add_middleware(
    ApitallyMiddleware,
    client_id="your-client-id",  # provided by Apitally
    env="default",  # or "dev", "prod" etc. (optional)
)

The middleware works asynchronously and does not impact the performance of your application. It also doesn't capture request and response headers and bodies, which means you don't have to worry about masking sensitive information that may be present in your API payloads.

Identifying consumers

You might find it useful to analyze API requests by consumer, so you can understand the different usage patterns of individual consumers. To allow that, you can optionally associate requests with consumers in your application by setting the apitally_consumer property on the request.state object.

As an example, if your application is using authentication, you could set the apitally_consumer based on the authenticated user.

You could do this anywhere within your existing authentication code, or in a dedicated function, like in the example below.

def identify_consumer(request: Request, current_user: Annotated[User, Depends(get_current_user)]):
    request.state.apitally_consumer = current_user.username

app = FastAPI(dependencies=[Depends(identify_consumer)])

Conclusion

While not as versatile and customizable as managing your own monitoring stack, using a tool like Apitally can provide valuable insights into how your API is being used a lot quicker. And sometimes a simple solution is all you need.

If you'd like to try Apitally out for your FastAPI project, you can follow the detailed setup guide for FastAPI. You should be good to go in less than 5 minutes.

Happy monitoring! Feel free to ask any questions or let me know what you think in the comments below.