fastapi_logging_samples

This repository provides a small FastAPI example demonstrating logging, exception sampling, OpenTelemetry instrumentation, and Prometheus metrics.

Quick links

• API docs: /docs (Swagger) and /redoc
• Metrics: /metrics (Prometheus)

Requirements

• Python 3.12+

Getting started

1. Create a virtual environment and install dependencies

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

2. Run the app with Uvicorn

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Alternatively with Docker:

docker build -t fastapi-logging-samples .
docker run -p 8000:8000 fastapi-logging-samples

Using the API

Open the interactive docs at http://localhost:8000/docs to try endpoints, or use curl as shown below.

Logging endpoints (prefix /logging)

• Send a debug-level message

curl "http://localhost:8000/logging/debug?message=hello-debug"

• Send an info-level message

curl "http://localhost:8000/logging/info?message=hello-info"

• Log an exception (calls logger.exception)

curl "http://localhost:8000/logging/exception?message=hello-exception"

• Log an exception with extra stack info

curl "http://localhost:8000/logging/exception_stack?message=hello-exc-stack"

• Log an error-level message

curl "http://localhost:8000/logging/error?message=hello-error"

• Log a critical-level message

curl "http://localhost:8000/logging/critical?message=hello-critical"

Error sampling endpoint (prefix /errors)

• Trigger a server-side error (stacktrace)

curl -i "http://localhost:8000/errors/stacktrace"

This endpoint intentionally raises an exception (division by zero) to demonstrate error/stacktrace logging and middleware handling.

fastapi_logging_samples — Quickstart (Docker)

A minimal FastAPI service exposing example logging and error routes, Prometheus metrics, and autogenerated API docs.

Quickstart — run the container

Pull and run the published image (binds container port 80 to host port 80):

docker pull ghcr.io/fcrozetta/fastapi_logging_samples:latest
docker run --rm -p 80:80 ghcr.io/fcrozetta/fastapi_logging_samples:latest

Or build and run locally:

docker build -t fastapi-logging-samples .
docker run --rm -p 80:80 fastapi-logging-samples

Useful endpoints (when running on localhost)

• API docs (Swagger UI): http://localhost/docs
• ReDoc: http://localhost/redoc
• Prometheus metrics: http://localhost/metrics

Environment variables (optional)

• LOG_FORMAT — override the logger output format (example: "%(name)s :: %(levelname)s :: %(message)s").
• OTEL_EXPORTER_OTLP_ENDPOINT — OTLP HTTP endpoint to send traces/logs (example: http://otel-collector:4318/v1/traces).
• OTEL_SERVICE_NAME — service name used by OpenTelemetry (example: fastapi-logging-samples).
• OTEL_RESOURCE_ATTRIBUTES — extra resource attributes (example: service.version=0.1.0).

OpenAPI tags — how to navigate the API

The Swagger UI groups routes by tags. Brief tag descriptions:

• logs — endpoints that emit application logs at different levels. Use these to generate log lines:

  • GET /logging/debug?message=... — emits DEBUG
  • GET /logging/info?message=... — emits INFO
  • GET /logging/exception?message=... — logs an exception (stack present in logs)
  • GET /logging/exception_stack?message=... — logs an exception with extra stack info
  • GET /logging/error?message=... — emits ERROR
  • GET /logging/critical?message=... — emits CRITICAL

• errors — endpoints that demonstrate server errors and stacktraces:

  • GET /errors/stacktrace — intentionally raises a division-by-zero error; expect HTTP 500 (useful to verify error capture).

Tips

• Open http://localhost/docs, expand a tag on the left to filter endpoints, click a route and use "Try it out" to call it.
• For quick manual tests copy the provided curl snippets from the UI or use the examples above.

That's it — run the image and open http://localhost/docs to explore the API.