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
- 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 )
- 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
- 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"}
- 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 .