मैनुअल ट्रेसिंग जोड़ें

स्पैन, लॉग और ट्रेस

यहाँ लॉगफायर का उपयोग करने का एक सरल उदाहरण है:

import time

import logfire

logfire.configure()

with logfire.span('This is a span'):
    time.sleep(1)
    logfire.info('This is an info log')
    time.sleep(2)

यदि आप इसे चलाते हैं, तो इसे कुछ इस तरह प्रिंट करना चाहिए:

Logfire project URL: https://logfire.pydantic.dev/my_username/my_project_name
21:02:55.078 This is a span
21:02:56.084   This is an info log

शुरुआती प्रोजेक्ट को लाइव दृश्य में निम्नलिखित प्रदर्शित करना चाहिए:

के साथ 1+ नीला बॉक्स इंगित करता है कि स्पैन में 1 तत्काल बच्चा है। अपने बच्चों को प्रदर्शित करने के लिए स्पैन का विस्तार करने के लिए बॉक्स पर क्लिक करें:

कृपया ध्यान दें:

1. with logfire.span(...)： ब्लॉक में बनाया गया कोई भी स्पैन या लॉग उस स्पैन का बच्चा होगा। यह आपको एक संरचित पेड़ में अपने लॉग को अच्छी तरह से व्यवस्थित करने की अनुमति देता है। आप इस अभिभावक-बच्चे के रिश्ते को इंडेंट-आधारित कंसोल लॉग में भी देख सकते हैं।

2. स्पैन में एक प्रारंभ समय और एक अंत समय होता है, और इसलिए एक अवधि होती है। इस अवधि को पूरा होने में 3 सेकंड लगते हैं।

3. लॉग के लिए, प्रारंभ और अंत समय समान हैं, इसलिए उनकी कोई अवधि नहीं है। हालाँकि, आप अभी भी यूआई में देख सकते हैं कि लॉग स्पैन शुरू होने के 1 सेकंड बाद और स्पैन समाप्त होने से 2 सेकंड पहले बनाए जाते हैं।

यदि आप शीर्ष नेविगेशन बार में "एक्सप्लोर" लिंक पर क्लिक करते हैं, तो आप आगे की खोज के लिए SQL लिख सकते हैं, उदाहरण के लिए:

ध्यान:

1. स्पैन और लॉग एक ही स्टोर में एक साथ संग्रहीत किए जाते हैं记录 मेज में।

2. लॉग इन करें的parent_span_id स्पैन हैspan_id...

3. दोनों में एक ही हैtrace_id आप इसे "लाइव" दृश्य में एक नया टैब खोलने के लिए क्लिक कर सकते हैं, जिसे फ़िल्टर किया गया हैट्रैक...

_ट्रैक_एक स्पैन / लॉग ट्री है जो एक ही रूट को साझा करता है। जब भी एक सक्रिय स्पैन के बिना एक नया स्पैन / लॉग बनाया जाता है, तो एक नया ट्रेस बनाया जाता है। यदि यह एक स्पैन है, तो उस स्पैन का कोई भी वंशज उसी ट्रेस का हिस्सा होगा। लॉग को अच्छी तरह से निशान में व्यवस्थित करने के लिए, उन्नत संचालन का प्रतिनिधित्व करने के लिए शीर्ष स्तर पर स्पैन बनाना सबसे अच्छा है, जैसे कि प्रसंस्करण वेब सर्वर अनुरोध।

विशेषता

स्पैन और लॉग को संरचित डेटा के साथ जोड़ा जा सकता है, जैसे:

logfire.info ('हैलो', नाम = 'वर्ल्ड')

यदि आप लाइव व्यू में "हैलो" लॉग पर क्लिक करते हैं, तो आपको दाईं ओर विवरण पैनल में निम्नलिखित देखना चाहिए:

यह डेटा JSप्रारूप में संग्रहीत है记录 तालिका属性 स्तंभ। उदाहरण के लिए, आप लाइव दृश्य के शीर्ष पर SQL फ़िल्टर का उपयोग कर सकते हैं attributes->>'name' = 'world' केवल इस लॉग को प्रदर्शित करने के लिए। इसका उपयोग किया जाता है记录 तालिका पर SQL क्वेरी WHERE खंड।

स्पैन और लॉग दोनों में ऐसे गुण हो सकते हैं जिनमें मनमाने मान होते हैं जो समझदारी से JSको आवश्यकतानुसार क्रमबद्ध किए जाते हैं। आप गुणों को सेट करने के लिए किसी भी कीवर्ड तर्क को पारित कर सकते हैं जब तक कि वे एक अंडरस्कोर (_) के साथ शुरू नहीं करते हैं। यह नामस्थान लॉगफायर-विशिष्ट अर्थों के साथ अतिरिक्त कीवर्ड मापदंडों के लिए आरक्षित है।

कभी-कभी इसे बनाने के बाद लेकिन पूरा होने से पहले गुणों को एक दायरे में संलग्न करना उपयोगी होता है। आप कॉल करके ऐसा कर सकते हैं span.set_attribute इस संक्रिया करने की विधि:

with logfire.span('Calculating...') as span:
    result = 1 + 2
    span.set_attribute('result', result)

संदेश और स्पैन नाम

यदि आप यह कोड चलाते हैं:

import logfire

logfire.configure()

for name in ['Alice', 'Bob', 'Carol']:
    logfire.info('Hello {name}', name=name)

यहाँ आप देख सकते हैं:

1. पहला पैरामीटर “Hello {name}” बन जानाspan_name स्तंभ का मूल्य। आप इसका उपयोग एक ही कोड से सभी रिकॉर्ड खोजने के लिए कर सकते हैं, भले ही संदेश अलग हों, उदाहरण के लिए SQL फ़िल्टर का उपयोग करना span_name = 'Hello {name}'...

2. स्पैन नाम का भी उपयोग किया जाता है str.format स्टाइल टेम्पलेट जो उत्पन्न करने के लिए गुणों के साथ स्वरूपित है消息 कॉलम। संदेश कंसोल लॉग और लाइव दृश्य में प्रदर्शित होता है।

आप इसे स्पैन शुरू होने के बाद भी सेट कर सकते हैं लेकिन स्पैन पूरा होने से पहले span.message उदाहरण के लिए:

with logfire.span('Calculating...') as span:
    result = 1 + 2
    span.message = f'Calculated: {result}'

आप उपयोग कर सकते हैं消息 प्रासंगिक रिकॉर्ड को फ़िल्टर करने के लिए, जैसे कि“Hello%”之类的消息 हाँ लेकिन हाँspan_name कॉलम फ़िल्टरिंग अधिक कुशल है क्योंकि यह अनुक्रमित है। फिर से, उपयोग करें span_name = 'Hello {name}' 和 attributes->>'name' = 'Alice' उपयोग करने से message = 'Hello Alice' बेहतर।

क्रमबद्ध करना संबंधित रिकॉर्ड, स्पैन नाम को प्रभावी ढंग से फ़िल्टर करने में सक्षम होने के लिए_आधार_कम होना चाहिए, जो माध्य उन्हें बहुत अधिक भिन्न नहीं होना चाहिए। उदाहरण के लिए, यह बुरा होगा:

name = get_username()
logfire.info('Hello ' + name, name=name)

क्योंकि अब span_name कॉलम में प्रत्येक उपयोगकर्ता नाम के लिए अलग-अलग मान होंगे। लेकिन यह ठीक है:

क्योंकि अब span_name स्तंभ में केवल दो मान हैं ('Goodbye {name}' और 'Hello {name}'), और फ़िल्टर किया गया span_name = 'Hello {name}' निस्पंदन से span_name = '{word} {name}' 和 attributes->>'word' = 'Hello' आसान और अधिक प्रभावी।

जब आप चाहते हैं कि स्पैन नाम संदेश टेम्पलेट से अलग हो, तो आप उपयोग कर सकते हैं _span_name पैरामीटर, जैसे:

word = 'Goodbye' if leaving else 'Hello'
logfire.info(word + ' {name}', name=name)

यह होगाspan_name पर सेट करें“Hello”, होगा消息 पर सेट करें“Hello world”。 कृपया ध्यान दें,_span_name पैरामीटर उन्हें गुणों से अलग करने के लिए एक अंडरस्कोर के साथ शुरू होते हैं।

logfire.info('Hello {name}', name='world', _span_name='Hello')

एफ-स्ट्रिंग्स

---

इसके स्थान पर:

logfire.info('Hello {name}', name=name)

तीन बार NAME को दोहराने से बचने के लिए F-String का उपयोग करना बहुत अधिक सुविधाजनक है:

logfire.info(f'Hello {name}')

पिछले खंड के विपरीत, यह पायथन 3.11+ में है_प्रभाव_अच्छा है, क्योंकि लॉगफायर विशेष जादू का उपयोग करेगाspan_name पर सेट करें“Hello {name}” और होगा name संपत्ति के लिए सेट है name चर का मूल्य, इसलिए यह पिछले कोड स्निपेट के बराबर है। यहां आपको जानने की आवश्यकता है:

• यह सुविधा पायथन 3.11+ में डिफ़ॉल्ट रूप से सक्षम है। आप उपयोग कर सकते हैं [logfire.configure(inspect_arguments=False)][logfire.configure(inspect_arguments)] इसे अक्षम करें। आप इसे पायथन 3.9 और 3.10 में भी सक्षम कर सकते हैं, लेकिन यह अधिक संभावना है कि यह ठीक से काम नहीं करेगा।

• सामान्य परिस्थितियों में, चेक पैरामीटर हमेशा मान्य होना चाहिए। यह ध्यान रखना महत्वपूर्ण है कि स्रोत कोड उपलब्ध होना चाहिए, इसलिए, उदाहरण के लिए, केवल तैनात .pyc फ़ाइल इसे विफल करने का कारण बनेगी।

• यदि मापदंडों की जाँच विफल हो जाती है, तो आपको एक चेतावनी प्राप्त होगी और एफ-स्ट्रिंग पैरामीटर का उपयोग स्वरूपण टेम्पलेट के रूप में किया जाएगा। माध्य आपको उच्च कार्डिनलिटी स्पैन नाम मिलेंगे जैसे कि“Hello Alice”, और नहीं名称 विशेषताएं, लेकिन जानकारी पूरी तरह से खो नहीं गई है।

• यदि जाँच पैरामीटर सक्षम है, तो मापदंडों की जाँच की जाएगी कि f स्ट्रिंग का उपयोग किया गया है या नहीं। इसलिए, यदि आप लिखते हैं logfire.info('Hello {name}'， name=name) यदि मापदंडों की जाँच विफल हो जाती है, तो आपको अभी भी एक चेतावनी प्राप्त होगी।

• एफ-स्ट्रिंग्स में मान फिर से लॉगफायर द्वारा मूल्यांकन और स्वरूपित किए जाते हैं। यह माध्य कि यदि get_username() (या जो कुछ भी यह रिटर्न का एक स्ट्रिंग रूपांतरण) महंगा है या इसके दुष्प्रभाव हैं, और आपको कुछ ऐसा उपयोग करने से बचना चाहिए logfire.info(f'Hello {get_username()}') कोड।

• पहला तर्क वास्तविक एफ स्ट्रिंग होना चाहिए।logfire.info(f'Hello {name}') यह काम करेगा, लेकिन message = f'Hello {name}'; logfire.info(message) नहीं।logfire.info('Hello ' + name) न ही मैं।

• जाँच मापदंडों को कैश किया जाता है ताकि एक ही एफ स्ट्रिंग की बार-बार जाँच में न्यूनतम प्रदर्शन ओवरहेड हो। हालांकि, पहली बार मापदंडों की जाँच करते समय बड़ी स्रोत फ़ाइलों को पार्स करना महत्वपूर्ण ओवरहेड को प्रभावित करता है। किसी भी तरह से, इस ओवरहेड से बचने के लिए पूरी तरह से चेक मापदंडों को अक्षम करने की आवश्यकता होती है, न कि केवल एफ स्ट्रिंग्स से बचना।

असामान्य

logfire.span संदर्भ प्रबंधक स्वचालित रूप से किसी भी अपवाद को लॉग इन करेगा जिसके कारण यह बाहर निकल गया, जैसे:

import logfire

logfire.configure()

with logfire.span('This is a span'):
    raise ValueError('This is an error')

यदि आप लाइव दृश्य में स्पैन पर क्लिक करते हैं, तो दाएं पैनल पर एक "अपवाद ट्रेसबैक" टैब होगा:

अपवाद जो पकड़े गए हैं लेकिन फिर से तैयार नहीं किए गए हैं, लॉग नहीं किए जाएंगे, उदाहरण के लिए:

with logfire.span('This is a span'):
    try:
        raise ValueError('This is an acceptable error not worth recording')
    except ValueError:
        pass

यदि आप नियंत्रित अपवादों को लॉग इन करना चाहते हैं, तो उपयोग करें span.record_exception विधि:

with logfire.span('This is a span') as span:
    try:
        raise ValueError('Catch this error, but record it')
    except ValueError as e:
        span.record_exception(e)

या, यदि आप केवल सामान्य मामलों के लिए स्पैन बनाए बिना अपवाद लॉग करना चाहते हैं, तो आप उपयोग कर सकते हैं logfire.exception यह क्या है?

try:
    raise ValueError('This is an error')
except ValueError:
    logfire.exception('Something went wrong')

logfire.exception(...) के बराबर logfire.error(...， _exc_info=True)。 यदि आप गैर-त्रुटि स्तर ट्रेसबैक लॉग करना चाहते हैं, तो आप भी कर सकते हैं _exc_info अन्य लॉगिंग विधियों के साथ उपयोग किया जाता है। यदि अपवाद ऑब्जेक्ट संसाधित नहीं किया जा रहा है, तो आप कर सकते हैं_exc_info अपवाद ऑब्जेक्ट पर सेट करें। अग्रणी अंडरस्कोर मत भूलना!

@logfire.instrument के साथ सुविधाजनक कार्यात्मक अवधि

आमतौर पर, आप पूरे फ़ंक्शन को एक अवधि में लपेटना चाहते हैं। ऐसा करने के बजाय:

def my_function(x, y):
    with logfire.span('my_function', x=x, y=y):
        ...

आप उपयोग कर सकते हैं @logfire.instrument डेकोरेटर:

डिफ़ॉल्ट रूप से, यह स्पैन में गुणों के रूप में फ़ंक्शन मापदंडों को जोड़ता है। इस सुविधा को अक्षम करने के लिए (उदाहरण के लिए, यदि पैरामीटर एक बड़ी वस्तु है जो एकत्र करने लायक नहीं है), उपयोग करें instrument(extract_args=False)。

डिफ़ॉल्ट स्पैन नाम के समान है Calling module_name.my_function आप पहले तर्क के रूप में एक वैकल्पिक स्पैन नाम पास कर सकते हैं instrument इसे टेम्पलेट के तर्क के रूप में भी स्वरूपित किया जा सकता है, जैसे:

@logfire.instrument('Applying my_function to {x=} and {y=}')
def my_function(x, y):
    ...

my_function(3, 4)
# Logs: Applying my_function to x=3 and y=4

!!! ध्यान

- ['@ लॉगफायर.इंस्ट्रूमेंट'][logfire.Logfire.instrument] डेकोरेटर्स को पहले लागू किया जाना चाहिए, यानी किसी अन्य डेकोरेटर के तहत।
- किसी फ़ंक्शन का स्रोत कोड सुलभ होना चाहिए।

लॉग स्तर

लॉग के विभिन्न स्तरों को बनाने के तरीके इस प्रकार हैं:

• logfire.trace
• logfire.debug
• logfire.info
• logfire.notice(日志火灾通知)
• logfire.warn
• logfire.error
• logfire.fatal

डिफ़ॉल्ट रूप से,跟踪 और 调试 लॉग छिपे हुए हैं। आप लाइव दृश्य में "डिफ़ॉल्ट स्तर" ड्रॉप-डाउन मेनू पर क्लिक करके इस सेटिंग को बदल सकते हैं:

आप भी उपयोग कर सकते हैं logfire.configure कंसोल लॉगिंग के लिए न्यूनतम स्तर सेट करें, उदाहरण के लिए:

import logfire

logfire.configure(console=logfire.ConsoleOptions(min_log_level='debug'))

चर स्तर के साथ संदेशों को लॉग करने के लिए, आप उपयोग कर सकते हैंlogfire.log, उदाहरण के लिए logfire.log('info'， 'This is an info log') के बराबर logfire.info('This is an info log')。

डिफ़ॉल्ट रूप से, अवधि स्तर है信息 आप उपयोग कर सकते हैं _level पैरामीटर इस पैरामीटर को बदलें, उदाहरण के लिए 使用 logfire.span('This is a debug span'， _level='debug')： आप स्पैन शुरू होने के बाद भी इसका उपयोग कर सकते हैं लेकिन स्पैन पूरा होने से पहले span.set_level स्तर बदलें। उदाहरण के लिए, लॉगफायरस्पैन सेट _ स्तर]:

with logfire.span('Doing a thing') as span:
    success = do_thing()
    if not success:
        span.set_level('error')

"वास्तविक समय" दृश्य में,अवधि अपनी उच्चतम रैंक और उसके वंशजों के अनुसार रंगीन हैउदाहरण के लिए, निम्नलिखित कोड:

import logfire

logfire.configure()

with logfire.span('Outer span'):
    with logfire.span('Inner span'):
        logfire.info('This is an info message')
        logfire.error('This is an error message')

यह इस तरह दिखाई देगा:

यहां, अवधि का स्तर अभी भी सेट है默认 जानकारी, लेकिन वे नीले रंग के बजाय लाल रंग के होते हैं क्योंकि उनमें त्रुटि लॉग होते हैं।

यदि स्पैन एक अनियंत्रित अपवाद के साथ समाप्त होता है, तो स्पैन का लॉग स्तर भी सेट किया जाता है错误 उपयोग span.record_exception ऐसा नहीं होता है। LogfireSpan। रिकॉर्ड _ अपवाद] विधि।

एक डेटाबेस में, लॉग स्तर संख्यात्मक रूप से संग्रहीत किए जाते हैं级别 स्तंभ। ये मान पर आधारित हैं, जैसे कि info के लिए 9 आप उपयोग कर सकते हैं level_num SQL फ़ंक्शन स्तर के नामों को संख्याओं में परिवर्तित करते हैं, जैसे कि级别 > level_num('info') सभी "अपवाद" रिकॉर्ड की तलाश करेंगे। आप भी उपयोग कर सकते हैं level_name SQL फ़ंक्शन संख्याओं को नामों में परिवर्तित करते हैं, उदाहरण के लिए SELECT level_name(level)、... "एक्सप्लोर" दृश्य में मानव-पठनीय स्तर देखें। ध्यान दें कि,level कॉलम अनुक्रमित हैं, इसलिए level = level_num('error') स्क्रीनिंग प्रभावी है, लेकिन level_name(level) = 'error' फ़िल्टरिंग अमान्य है।

---

本文总阅读量次