OpenTelemetry¶

जब आपका API चल रहा होता है, तो आप शायद जानना चाहें कि उसे कितना ट्रैफ़िक मिल रहा है, कौन-से requests धीमे हैं और त्रुटियाँ कब होती हैं।

Telemetry आपके एप्लिकेशन के व्यवहार से जुड़ा data है, जो इन सवालों के जवाब देने में मदद करता है। इसके सामान्य प्रकार हैं:

• Metrics: ऐसे माप जिन्हें आप समय के साथ संक्षेप में देख सकते हैं, जैसे response में लगने वाला समय और संभाले जा रहे requests की संख्या।
• Traces: अलग-अलग requests और उन्हें संभालने के लिए किए गए ऑपरेशन के रिकॉर्ड। हर ऑपरेशन जिसका समय मापा जाता है, एक span कहलाता है।
• Logs: टाइमस्टैम्प के साथ event के रिकॉर्ड, जैसे किसी एप्लिकेशन का शुरू होना या किसी ऑपरेशन का विफल होना।

OpenTelemetry telemetry एकत्र करने और उसे किसी मॉनिटरिंग सेवा को भेजने के लिए standards और tools का एक समूह है, जहाँ आप उसे डैशबोर्ड में देख और जाँच सकते हैं।

FastAPI, HTTP request traces, metrics और logs के लिए default रूप से OpenTelemetry support प्रदान करता है। WebSocket कनेक्शन भी traces और logs प्रदान करते हैं। उस data को देखने के लिए, उसे प्राप्त करने वाली मॉनिटरिंग सेवा कॉन्फ़िगर करें।

FastAPI install करें¶

FastAPI को standard extras के साथ install करें, जिनमें telemetry भेजने के लिए packages शामिल हैं:

$ uv add "fastapi[standard]"
---> 100%

ऐप बनाएँ¶

एक file main.py बनाएँ:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

ध्यान दें कि यह सब default रूप से काम करता है। Telemetry के काम करने के लिए आपको कोई कस्टम कोड लिखने की ज़रूरत नहीं है।

FastAPI Cloud¶

जब आप fastapi[standard] के साथ FastAPI Cloud पर डिप्लॉय करते हैं, तो metrics अपने आप काम करते हैं। आपको कुछ और कॉन्फ़िगर नहीं करना पड़ता।

Pro प्लान पर, आप Metrics डैशबोर्ड में requests की संख्या, त्रुटि दर और response में लगने वाला समय देख सकते हैं।

अन्य मॉनिटरिंग सेवाएँ¶

किसी अन्य मॉनिटरिंग सेवा को telemetry भेजने के लिए, ऐसा endpoint कॉन्फ़िगर करें जो OTLP स्वीकार करता हो। यह telemetry भेजने के लिए OpenTelemetry का प्रोटोकॉल है। सेवा के HTTP/protobuf बेस endpoint का उपयोग करें।

उदाहरण URL की जगह अपना endpoint डालकर, ये environment variables सेट करें:

export OTEL_SERVICE_NAME=my-api
export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com

OTEL_SERVICE_NAME मॉनिटरिंग सेवा में आपके ऐप की पहचान करता है। Endpoint, data प्राप्त करने के लिए बेस URL है। उस URL के अंतर्गत traces को /v1/traces, metrics को /v1/metrics और logs को /v1/logs पर भेजा जाता है।

यदि आपकी सेवा को प्रमाणीकरण की ज़रूरत है, तो OTEL_EXPORTER_OTLP_HEADERS में उसके बताए गए headers सेट करें, उदाहरण के लिए api-key=YOUR_API_KEY।

ऐप चलाएँ¶

उसी टर्मिनल में ऐप शुरू करें:

$ uv run fastapi run

दूसरे टर्मिनल में, एक request भेजें:

$ curl http://127.0.0.1:8000/items/1
{"item_id":1}

अपनी मॉनिटरिंग सेवा खोलें और my-api खोजें। अगले एक्सपोर्ट के बाद, आप GET /items/{item_id} span वाला एक trace देख सकते हैं, साथ ही requests की संख्या, response की अवधि और सक्रिय requests के metrics भी देख सकते हैं।

Telemetry को अपनी ज़रूरत के अनुसार बदलें¶

Providers और exporters कॉन्फ़िगर करें¶

एक provider ऐसे ऑब्जेक्ट प्रदान करता है जो traces, metrics या logs रिकॉर्ड करते हैं। उसका कॉन्फ़िगरेशन नियंत्रित करता है कि उस data को कैसे प्रोसेस और एक्सपोर्ट किया जाता है।

Telemetry लाइब्रेरी OpenTelemetry के ग्लोबल providers को कॉन्फ़िगर कर सकती हैं। ऐप शुरू होने से पहले लाइब्रेरी को कॉन्फ़िगर करें, और FastAPI अपने आप उन providers का उपयोग करता है।

जब environment में कोई OTLP endpoint सेट होता है, तो FastAPI हर सक्षम provider में उस गंतव्य के लिए एक exporter जोड़ता है। मौजूदा exporters अपने गंतव्यों पर data भेजना जारी रखते हैं।

हर गंतव्य को एक बार कॉन्फ़िगर करें। यदि कोई दूसरी लाइब्रेरी पहले से ही environment में दिए गए गंतव्य को संभाल रही है, तो उसका environment export अक्षम करें या FastAPI का स्वचालित setup बंद करें:

app = FastAPI(telemetry={"auto_configure": False})

आप telemetry डिक्शनरी में सीधे एक provider भी पास कर सकते हैं। उदाहरण के लिए, यह provider आपके टर्मिनल में request spans प्रिंट करने के लिए OpenTelemetry के console exporter का उपयोग करता है:

from fastapi import FastAPI
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

app = FastAPI(telemetry={"tracer_provider": tracer_provider})


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Exporter, spans को उनके गंतव्य पर भेजता है। BatchSpanProcessor, spans को समूहों में बाँटता है और उन्हें बैकग्राउंड में भेजता है। अपनी मॉनिटरिंग लाइब्रेरी के गंतव्य का उपयोग करने के लिए console exporter की जगह उस लाइब्रेरी द्वारा प्रदान किया गया exporter लगाएँ। कॉन्फ़िगरेशन के और विकल्पों के लिए OpenTelemetry की Python instrumentation गाइड देखें।

Metrics या logs provider प्रदान करने के लिए उसी डिक्शनरी में meter_provider या logger_provider का उपयोग करें। Provider बनाने वाला एप्लिकेशन या लाइब्रेरी उसके shutdown को संभालता है। FastAPI अपने जोड़े गए एक्सपोर्ट घटकों को संभालता है।

Request ऑपरेशन को ट्रेस करें¶

Default रूप से, request traces में dependencies रिज़ॉल्व करने, आपका path operation function चलाने, response को serialize करने और FastAPI के BackgroundTasks में हर टास्क को चलाने के spans शामिल होते हैं। ये spans उसी provider और उन्हीं exporters का उपयोग करते हैं।

बैकग्राउंड टास्क के spans, request के trace का हिस्सा बने रहते हैं। वे HTTP response span समाप्त होने के बाद चलते हैं, इसलिए वे मापे गए response समय को नहीं बढ़ाते।

केवल HTTP request span रिकॉर्ड करने के लिए, operation_spans को False पर सेट करें:

from fastapi import FastAPI

app = FastAPI(telemetry={"operation_spans": False})


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

WebSocket कनेक्शन को ट्रेस करें¶

हर WebSocket कनेक्शन का एक span होता है, जैसे WS /ws/{room}, जो हैंडलर और dependency cleanup को कवर करता है। यह उन्हीं providers और सेटिंग्स का उपयोग करता है, जिनमें dependency resolution और endpoint के निष्पादन के लिए operation_spans भी शामिल है।

HTTP request metrics में केवल HTTP requests शामिल होते हैं। कोड 1000 या 1001 के साथ होने वाले सामान्य WebSocket डिस्कनेक्ट, error logs नहीं बनाते।

त्रुटियों की जाँच करें¶

FastAPI, संभाले न गए exceptions को OpenTelemetry logs के रूप में रिकॉर्ड करता है, जो request या कनेक्शन के trace से जुड़े होते हैं। Error logs तब भी रिकॉर्ड किए जाते हैं जब trace को सैंपल नहीं किया जाता।

Exception logs में exception का प्रकार, संदेश और stack trace शामिल होते हैं। संदेशों और stack traces में संवेदनशील जानकारी हो सकती है। उन्हें फ़िल्टर करने या उनमें से संवेदनशील जानकारी हटाने के लिए अपने provider के log processors का उपयोग करें, या इन logs को अक्षम करने के लिए logs को False पर सेट करें।

FastAPI, request validation की विफलताओं को भी route और त्रुटियों की संख्या के साथ warning logs के रूप में रिकॉर्ड करता है। इन logs में अमान्य इनपुट शामिल नहीं होता।

चुनें कि क्या रिकॉर्ड करना है¶

telemetry डिक्शनरी इन सेटिंग्स को भी स्वीकार करती है:

उदाहरण के लिए, health checks को छोड़कर metrics एकत्र करने के लिए:

from fastapi import FastAPI

app = FastAPI(
    telemetry={
        "tracing": False,
        "exclude": lambda scope: scope["path"] == "/health",
    }
)

जब आपका एप्लिकेशन provider setup खुद संभालता हो, जैसे अपने lifespan function के अंदर, तो auto_configure को False पर सेट करें।