FastAPI OTEL Common Skill

This skill provides the AI agent with specialized knowledge and best practices for the fastapi-otel-common ecosystem.

Core Principles

• Observability First: Always implement OpenTelemetry tracing and metrics. Use the built-in instrumentation.
• Structured Logging: Use loguru for all logging. Avoid print(). Use the library’s logger initialization.
• Security by Default: Use get_current_user or role-based decorators (RequireRoles) for protected endpoints.
• Production-Ready Health Checks: Utilize the automatic /healthz, /readyz, and /livez endpoints.

Common Tasks

1. Initialize the App

from fastapi_otel_common import create_app

app = create_app(
    title="My Service",
    version="1.0.0",
    # All security headers and OTEL instrumentation are enabled by default
)

2. Add OIDC Protected Route

from fastapi import Depends
from fastapi_otel_common.security import get_current_user
from fastapi_otel_common.core.models import UserBase

@app.get("/me")
async def get_me(user: UserBase = Depends(get_current_user)):
    return user

3. Implement Role-Based Access Control

from fastapi_otel_common.security import RequireRoles

@app.post("/admin/action")
async def admin_action(
    user: UserBase = Depends(RequireRoles(["admin"]))
):
    return {"status": "success"}

4. Custom Tracing

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

async def some_logic():
    with tracer.start_as_current_span("my-custom-operation"):
        # Logic here
        pass

Troubleshooting

• No Traces in Collector: Check OTEL_EXPORTER_OTLP_ENDPOINT environment variable.
• DB Connection Issues: Ensure DB_TYPE and associated credentials (e.g., POSTGRES_USER, SQLITE_DB_PATH) are set.
• Authentication Fails: Verify OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_JWKS_URI.