OpenTelemetry屬性命名的五個(gè)最佳實(shí)踐

作者：岱軍 2023-12-06 07:24:42

追蹤數(shù)據(jù)收集是觀測性的一個(gè)必要部分。但這需要建立一套流程，以確保數(shù)據(jù)是有用的、可訪問的，并且具有洞察力。命名規(guī)范需要一些前期工作，但通過采納這些最佳實(shí)踐 —— 從確保語義清晰和維護(hù)統(tǒng)一庫到了解數(shù)據(jù)、與服務(wù)水平保持一致，以及預(yù)測新的用例 —— 您的團(tuán)隊(duì)可以提升遙測的效用。

在故障排除和事后分析中，為了使數(shù)據(jù)具有價(jià)值，屬性名稱需要在每種遙測類型、工具和服務(wù)中保持一致。

譯自Top 5 Best Practices for Naming OpenTelemetry Attributes，作者 Carl Brahms 是Chronosphere客戶成功團(tuán)隊(duì)的成員，擁有多年的監(jiān)控、觀測和事件管理平臺(tái)經(jīng)驗(yàn)。他對三件事情充滿激情：協(xié)助團(tuán)隊(duì)發(fā)現(xiàn)實(shí)時(shí)數(shù)據(jù)洞察、生成式人工智能以及...

當(dāng)涉及使用OpenTelemetry（OTel）分布式追蹤數(shù)據(jù)時(shí)，僅僅收集數(shù)據(jù)是不夠的；您需要采取措施確保數(shù)據(jù)易于查找并與其他數(shù)據(jù)相關(guān)聯(lián)。這就是制定良好屬性命名標(biāo)準(zhǔn)的目的。

有效的屬性命名不僅僅是一種最佳實(shí)踐；它是一項(xiàng)關(guān)鍵要求。為了使數(shù)據(jù)在故障排除和事后分析中具有價(jià)值，屬性名稱需要在每個(gè)遙測類型、每個(gè)工具和每個(gè)服務(wù)中保持一致。如果缺乏這種一致性，您的 OTel 數(shù)據(jù)的實(shí)用性將大大降低。

OTel 的語義約定和最佳實(shí)踐使數(shù)據(jù)在云原生環(huán)境中更加互連、可移植和可用。上下文數(shù)據(jù)是可觀測性團(tuán)隊(duì)中最有益的數(shù)據(jù)類型，而最佳實(shí)踐確保您可以最大化數(shù)據(jù)的使用和效果。

這些準(zhǔn)則和最佳實(shí)踐將有助于使您的組織從收集的追蹤數(shù)據(jù)中獲得最大的利益。

建立 OTel 屬性的有效采用

要實(shí)施有效和有用的 OTel 屬性，早期涉及所有受影響的團(tuán)隊(duì)至關(guān)重要。為了取得成功的采用，您應(yīng)考慮組織研討會(huì)，讓每個(gè)人都了解在整個(gè)堆棧的所有層面上都有清晰一致的命名標(biāo)準(zhǔn)帶來的積極結(jié)果。一致性創(chuàng)造清晰度，在事件響應(yīng)和調(diào)試過程中至關(guān)重要。

得到軟件和系統(tǒng)架構(gòu)師的支持，通過說明命名標(biāo)準(zhǔn)的好處并專注于與貴公司和應(yīng)用程序相關(guān)的領(lǐng)域。

然后起草一份詳細(xì)的文件，概述命名約定，包括語法、結(jié)構(gòu)和示例。制定一個(gè)修改標(biāo)準(zhǔn)的過程，通過反饋改進(jìn)它，并在事后處理發(fā)現(xiàn)的任何空白。

命名 OTel 屬性的最佳實(shí)踐

有五個(gè)主要的最佳實(shí)踐，作為您的 OTel 屬性命名約定的一部分，以充分利用您的可觀測性數(shù)據(jù)。

1. 使用語義和描述性屬性

語義名稱有助于確保高效的根本原因分析。

確保您的屬性清晰、描述性，并適用于它們描述的資源的整體。諸如http.status_code和db.system這樣的名稱易于識(shí)別，并立即提供關(guān)于問題性質(zhì)的見解，無論是在數(shù)據(jù)庫還是在 Web 服務(wù)中。
非語義名稱如attribute、info或session_data太通用，在后期分析遙測數(shù)據(jù)時(shí)會(huì)導(dǎo)致混淆。

示例：app.service.version

為您的屬性定義命名空間。
示例：
app.component.name
當(dāng)多個(gè)服務(wù)團(tuán)隊(duì)擁有自己的標(biāo)準(zhǔn)屬性時(shí)，這點(diǎn)尤為重要。
保持屬性名稱簡短。
示例：
http.url
在錯(cuò)誤跨度上設(shè)置錯(cuò)誤屬性。
示例：
client.error

使用描述性的屬性名稱，您可以輕松查看資源并具備了解其內(nèi)容和關(guān)聯(lián)性的所有必要上下文。要了解現(xiàn)有語義約定的出色解釋，請?jiān)L問官方規(guī)范，您可以在那里學(xué)到一般和系統(tǒng)屬性，并按信號或操作類型（如HTTP或數(shù)據(jù)庫）組織它們，包括技術(shù)特定的約定。

2. 使用共享庫

創(chuàng)建已知屬性的庫的實(shí)踐有助于對您關(guān)心的數(shù)據(jù)進(jìn)行編目，其文檔記錄了對客戶而言重要的數(shù)據(jù)。

當(dāng)多個(gè)團(tuán)隊(duì)將共享屬性時(shí)，標(biāo)準(zhǔn)化它們以避免差異至關(guān)重要。跨團(tuán)隊(duì)的屬性命名約定差異可能使關(guān)聯(lián)數(shù)據(jù)變得困難或根本不可能。例如，如果后端團(tuán)隊(duì)將延遲命名為latency，而前端團(tuán)隊(duì)將其命名為duration，查詢比較或聚合跨服務(wù)的延遲將無法正常工作。標(biāo)準(zhǔn)化的屬性使團(tuán)隊(duì)能夠利用共享資源（比如儀表板或警報(bào)），并允許您在多個(gè)系統(tǒng)和服務(wù)之間獲得洞見。

3. 創(chuàng)建自定義屬性

有時(shí)，您可能需要為公司或應(yīng)用程序的特定方面創(chuàng)建新屬性。在這樣做之前，最好先查閱 OpenTelemetry屬性注冊表，以確保您需要的屬性不存在。一旦確認(rèn)沒有與您需要的匹配的屬性，您就可以創(chuàng)建一個(gè)新屬性。在創(chuàng)建過程中，遵循OTel 屬性命名指南中的提示尤為重要，特別是關(guān)于使用前綴的部分。

在屬性名稱中使用前綴有助于區(qū)分您的自定義屬性名稱與標(biāo)準(zhǔn)名稱、其他項(xiàng)目選擇的名稱、與您合作的供應(yīng)商或公司選擇的名稱。如果自定義屬性意外地與另一個(gè)屬性共享名稱，可能會(huì)導(dǎo)致錯(cuò)誤的結(jié)論和決策、有缺陷的儀表板和警報(bào)，并使跟蹤事務(wù)的流程或狀態(tài)變得困難。

為避免與其他項(xiàng)目、供應(yīng)商或公司發(fā)生沖突，明智的做法是考慮使用基于公司域名的前綴，以相反的順序，例如io.chronosphere.myapp。

即使您確定該名稱絕對不會(huì)在您的應(yīng)用程序之外使用，僅在公司內(nèi)部使用，前綴仍然是防止沖突的重要手段。考慮使用與您的應(yīng)用程序或項(xiàng)目相關(guān)聯(lián)的前綴名稱，例如bluebook.widget_count。

你可能會(huì)想要利用屬于 OpenTelemetry 或其他項(xiàng)目或供應(yīng)商的現(xiàn)有前綴。共享前綴可能導(dǎo)致后續(xù)發(fā)生名稱沖突，使您和同事在事故期間努力找到將他人的數(shù)據(jù)與您的數(shù)據(jù)分開的方法。

4. 注重服務(wù)水平

在決定要應(yīng)用于您的跟蹤的屬性時(shí)，請記住您的應(yīng)用程序的重點(diǎn)是為客戶提供高質(zhì)量的軟件體驗(yàn)。這一使命被編碼在您服務(wù)/應(yīng)用程序的服務(wù)水平目標(biāo)（SLOs）中，可能以 99.999% 的正常運(yùn)行時(shí)間期望的形式存在。從 SLO 中，您可以縮小到哪些服務(wù)水平指標(biāo)（SLIs）最好支持或最有可能威脅實(shí)現(xiàn) SLOs。您的屬性應(yīng)支持您的服務(wù)水平。

例如，如果您在流量的不同部分之間有延遲 SLO，使用提供段維度的屬性，如 ProductID、FeatureID 或 RegionID，可以幫助您相應(yīng)地組織警報(bào)。

5. 思考新的用例

將屬性視為分布式系統(tǒng)中模式匹配的根源。如果您想要調(diào)查跨類別和類別之間的關(guān)系，屬性是排序和比較的工具。

逐步嘗試不同的屬性，看看會(huì)有什么變化。讓我們考慮一個(gè)例子。

你的高級客戶是否因發(fā)票錯(cuò)誤而聯(lián)系支持？難道訂單服務(wù)不是幾分鐘前部署了新版本嗎？對比屬性，例如service.version和membership.level，對服務(wù)名稱為 order 的錯(cuò)誤指標(biāo)進(jìn)行關(guān)聯(lián)，可以幫助確定高級會(huì)員的升高錯(cuò)誤率是否與訂單服務(wù)的新版本高度相關(guān)。

有用的屬性類型

在制定 OpenTelemetry 的標(biāo)準(zhǔn)屬性時(shí)進(jìn)行了大量慎重考慮，而這個(gè)列表一直在不斷發(fā)展。盡管這里無法提及所有類別，但在制定內(nèi)部命名標(biāo)準(zhǔn)時(shí)探索現(xiàn)有內(nèi)容并強(qiáng)調(diào)在調(diào)查回歸時(shí)對團(tuán)隊(duì)有用的內(nèi)容可能會(huì)很有幫助。以下是注冊表中的一些示例：

常規(guī)屬性：常規(guī)屬性提供有關(guān)整體環(huán)境和網(wǎng)絡(luò)的廣泛背景信息。

server.address：服務(wù)器的地址。

destination.address：目標(biāo)的地址。

network.carrier.name：網(wǎng)絡(luò)承載方的名稱。

code.filepath：代碼的文件路徑。

消息系統(tǒng)：與消息系統(tǒng)相關(guān)的屬性，有助于跟蹤和診斷消息處理中的問題。
messaging.destination：
描述消息發(fā)布到的邏輯實(shí)體。
messaging.kafka.consumer.group：
處理消息的 Kafka 消費(fèi)者組。
messaging.message.body.size：
消息主體的大小（字節(jié)）。
HTTP：對于跟蹤 HTTP 請求和響應(yīng)至關(guān)重要，提供有關(guān) Web 事務(wù)的見解。
http.url：
完整的 HTTP 請求 URL。
http.status_code：
HTTP 響應(yīng)狀態(tài)碼。
user_agent.original：
客戶端的 HTTP User-Agent 頭的值。
資源屬性：這些屬性提供有關(guān)服務(wù)、基礎(chǔ)設(shè)施和操作環(huán)境的詳細(xì)背景信息。
service.version：
服務(wù)的版本。
k8s.cluster.name：
Kubernetes 集群的名稱。
gcp.gce.instance.name：
Google Compute Engine 實(shí)例的名稱。
aws.ecs.container.arn：
ECS 容器的 Amazon 資源名稱（ARN）。

那事件呢？

有一種特殊類型的跨度屬性稱為跨度事件日志經(jīng)常被忽視。跨度事件與日志非常相似，但它們是放置上下文信息的好地方，這些信息在故障排除事務(wù)問題時(shí)可能非常有用。

在考慮要放入跨度事件日志的內(nèi)容時(shí)，應(yīng)清理任何私人用戶數(shù)據(jù)的有效負(fù)載/添加跨度內(nèi)發(fā)生的任何事件，包括所發(fā)生事件的簡要摘要、任何異常或完整的錯(cuò)誤消息，以及額外的上下文信息。

避免的屬性實(shí)踐

我們一直在關(guān)注屬性的“做法”，但這里更仔細(xì)地看一下一些要避免的屬性陷阱。

使用晦澀的語義屬性名稱，比如errorcode，只會(huì)引起混淆，使獲取信息變得更加困難。
使用otel.*命名空間，除非您認(rèn)為該名稱適用于行業(yè)中的其他應(yīng)用。在這種情況下，您可以提交提案，將新名稱添加到語義約定中。
創(chuàng)建您不使用的屬性，即使看起來將來可能對某人有用。除非有確鑿的證據(jù)證明屬性的有用性，最好還是暫時(shí)不要添加。
將堆棧跟蹤、uuid（唯一用戶標(biāo)識(shí)）或異常信息放入自定義屬性。建議在發(fā)生時(shí)將它們記錄為跨度上的Event，并且事件的名稱必須為 "exception"。詳見規(guī)范中的異常部分。
屬性鍵重復(fù) —— 要么覆蓋同一跨度上的鍵，要么擁有兩個(gè)具有不同名稱的相同值。重復(fù)的屬性鍵可能會(huì)引起沖突并覆蓋數(shù)據(jù)。它還使查詢和分析變得復(fù)雜。
未設(shè)置或空值。未設(shè)置的值提供不了有用的信息。沒有值的屬性占用存儲(chǔ)空間，但對故障排除或分析沒有幫助。它們還可能通過扭曲總數(shù)來扭曲分析。這也會(huì)引起混淆。

在 OpenTelemetry 文檔中還有更多有用的見解和建議，因此在制定屬性標(biāo)準(zhǔn)時(shí)建議查閱最新的規(guī)范。