OpenTelemetry屬性命名的五個最佳實踐
在故障排除和事后分析中，為了使數據具有價值，屬性名稱需要在每種遙測類型、工具和服務中保持一致。
譯自Top 5 Best Practices for Naming OpenTelemetry Attributes，作者 Carl Brahms 是Chronosphere客戶成功團隊的成員，擁有多年的監控、觀測和事件管理平臺經驗。他對三件事情充滿激情：協助團隊發現實時數據洞察、生成式人工智能以及...
當涉及使用OpenTelemetry（OTel）分布式追蹤數據時，僅僅收集數據是不夠的；您需要采取措施確保數據易于查找并與其他數據相關聯。這就是制定良好屬性命名標準的目的。
有效的屬性命名不僅僅是一種最佳實踐；它是一項關鍵要求。為了使數據在故障排除和事后分析中具有價值，屬性名稱需要在每個遙測類型、每個工具和每個服務中保持一致。如果缺乏這種一致性，您的 OTel 數據的實用性將大大降低。
OTel 的語義約定和最佳實踐使數據在云原生環境中更加互連、可移植和可用。上下文數據是可觀測性團隊中最有益的數據類型，而最佳實踐確保您可以最大化數據的使用和效果。
這些準則和最佳實踐將有助于使您的組織從收集的追蹤數據中獲得最大的利益。
建立 OTel 屬性的有效采用
要實施有效和有用的 OTel 屬性，早期涉及所有受影響的團隊至關重要。為了取得成功的采用，您應考慮組織研討會，讓每個人都了解在整個堆棧的所有層面上都有清晰一致的命名標準帶來的積極結果。一致性創造清晰度，在事件響應和調試過程中至關重要。
得到軟件和系統架構師的支持，通過說明命名標準的好處并專注于與貴公司和應用程序相關的領域。
然后起草一份詳細的文件，概述命名約定，包括語法、結構和示例。制定一個修改標準的過程，通過反饋改進它，并在事后處理發現的任何空白。
命名 OTel 屬性的最佳實踐
有五個主要的最佳實踐，作為您的 OTel 屬性命名約定的一部分，以充分利用您的可觀測性數據。
1. 使用語義和描述性屬性
語義名稱有助于確保高效的根本原因分析。
- 確保您的屬性清晰、描述性，并適用于它們描述的資源的整體。諸如http.status_code和db.system這樣的名稱易于識別，并立即提供關于問題性質的見解，無論是在數據庫還是在 Web 服務中。
- 非語義名稱如attribute、info或session_data太通用，在后期分析遙測數據時會導致混淆。
示例：app.service.version
- 為您的屬性定義命名空間。
示例：
app.component.name
當多個服務團隊擁有自己的標準屬性時，這點尤為重要。
保持屬性名稱簡短。
示例：
http.url
在錯誤跨度上設置錯誤屬性。
示例：
client.error
使用描述性的屬性名稱，您可以輕松查看資源并具備了解其內容和關聯性的所有必要上下文。要了解現有語義約定的出色解釋，請訪問官方規范，您可以在那里學到一般和系統屬性，并按信號或操作類型（如HTTP或數據庫）組織它們，包括技術特定的約定。
2. 使用共享庫
創建已知屬性的庫的實踐有助于對您關心的數據進行編目，其文檔記錄了對客戶而言重要的數據。
當多個團隊將共享屬性時，標準化它們以避免差異至關重要。跨團隊的屬性命名約定差異可能使關聯數據變得困難或根本不可能。例如，如果后端團隊將延遲命名為latency，而前端團隊將其命名為duration，查詢比較或聚合跨服務的延遲將無法正常工作。標準化的屬性使團隊能夠利用共享資源（比如儀表板或警報），并允許您在多個系統和服務之間獲得洞見。
3. 創建自定義屬性
有時，您可能需要為公司或應用程序的特定方面創建新屬性。在這樣做之前，最好先查閱 OpenTelemetry屬性注冊表，以確保您需要的屬性不存在。一旦確認沒有與您需要的匹配的屬性，您就可以創建一個新屬性。在創建過程中，遵循OTel 屬性命名指南中的提示尤為重要，特別是關于使用前綴的部分。
在屬性名稱中使用前綴有助于區分您的自定義屬性名稱與標準名稱、其他項目選擇的名稱、與您合作的供應商或公司選擇的名稱。如果自定義屬性意外地與另一個屬性共享名稱，可能會導致錯誤的結論和決策、有缺陷的儀表板和警報，并使跟蹤事務的流程或狀態變得困難。
為避免與其他項目、供應商或公司發生沖突，明智的做法是考慮使用基于公司域名的前綴，以相反的順序，例如io.chronosphere.myapp。
即使您確定該名稱絕對不會在您的應用程序之外使用，僅在公司內部使用，前綴仍然是防止沖突的重要手段。考慮使用與您的應用程序或項目相關聯的前綴名稱，例如bluebook.widget_count。
你可能會想要利用屬于 OpenTelemetry 或其他項目或供應商的現有前綴。共享前綴可能導致后續發生名稱沖突，使您和同事在事故期間努力找到將他人的數據與您的數據分開的方法。
4. 注重服務水平
在決定要應用于您的跟蹤的屬性時，請記住您的應用程序的重點是為客戶提供高質量的軟件體驗。這一使命被編碼在您服務/應用程序的服務水平目標（SLOs）中，可能以 99.999% 的正常運行時間期望的形式存在。從 SLO 中，您可以縮小到哪些服務水平指標（SLIs）最好支持或最有可能威脅實現 SLOs。您的屬性應支持您的服務水平。
例如，如果您在流量的不同部分之間有延遲 SLO，使用提供段維度的屬性，如 ProductID、FeatureID 或 RegionID，可以幫助您相應地組織警報。
5. 思考新的用例
將屬性視為分布式系統中模式匹配的根源。如果您想要調查跨類別和類別之間的關系，屬性是排序和比較的工具。
逐步嘗試不同的屬性，看看會有什么變化。讓我們考慮一個例子。
你的高級客戶是否因發票錯誤而聯系支持？難道訂單服務不是幾分鐘前部署了新版本嗎？對比屬性，例如service.version和membership.level，對服務名稱為 order 的錯誤指標進行關聯，可以幫助確定高級會員的升高錯誤率是否與訂單服務的新版本高度相關。
有用的屬性類型
在制定 OpenTelemetry 的標準屬性時進行了大量慎重考慮，而這個列表一直在不斷發展。盡管這里無法提及所有類別，但在制定內部命名標準時探索現有內容并強調在調查回歸時對團隊有用的內容可能會很有幫助。以下是注冊表中的一些示例：
- 常規屬性：常規屬性提供有關整體環境和網絡的廣泛背景信息。
server.address：服務器的地址。
destination.address：目標的地址。
network.carrier.name：網絡承載方的名稱。
code.filepath：代碼的文件路徑。
- 消息系統：與消息系統相關的屬性，有助于跟蹤和診斷消息處理中的問題。
messaging.destination：
描述消息發布到的邏輯實體。
messaging.kafka.consumer.group：
處理消息的 Kafka 消費者組。
messaging.message.body.size：
消息主體的大小（字節）。
HTTP：對于跟蹤 HTTP 請求和響應至關重要，提供有關 Web 事務的見解。
http.url：
完整的 HTTP 請求 URL。
http.status_code：
HTTP 響應狀態碼。
user_agent.original：
客戶端的 HTTP User-Agent 頭的值。
資源屬性：這些屬性提供有關服務、基礎設施和操作環境的詳細背景信息。
service.version：
服務的版本。
k8s.cluster.name：
Kubernetes 集群的名稱。
gcp.gce.instance.name：
Google Compute Engine 實例的名稱。
aws.ecs.container.arn：
ECS 容器的 Amazon 資源名稱（ARN）。
那事件呢？
有一種特殊類型的跨度屬性稱為跨度事件日志經常被忽視。跨度事件與日志非常相似，但它們是放置上下文信息的好地方，這些信息在故障排除事務問題時可能非常有用。
在考慮要放入跨度事件日志的內容時，應清理任何私人用戶數據的有效負載/添加跨度內發生的任何事件，包括所發生事件的簡要摘要、任何異常或完整的錯誤消息，以及額外的上下文信息。
避免的屬性實踐
我們一直在關注屬性的“做法”，但這里更仔細地看一下一些要避免的屬性陷阱。
- 使用晦澀的語義屬性名稱，比如errorcode，只會引起混淆，使獲取信息變得更加困難。
- 使用otel.*命名空間，除非您認為該名稱適用于行業中的其他應用。在這種情況下，您可以提交提案，將新名稱添加到語義約定中。
- 創建您不使用的屬性，即使看起來將來可能對某人有用。除非有確鑿的證據證明屬性的有用性，最好還是暫時不要添加。
- 將堆棧跟蹤、uuid（唯一用戶標識）或異常信息放入自定義屬性。建議在發生時將它們記錄為跨度上的Event，并且事件的名稱必須為 "exception"。詳見規范中的異常部分。
- 屬性鍵重復 —— 要么覆蓋同一跨度上的鍵，要么擁有兩個具有不同名稱的相同值。重復的屬性鍵可能會引起沖突并覆蓋數據。它還使查詢和分析變得復雜。
- 未設置或空值。未設置的值提供不了有用的信息。沒有值的屬性占用存儲空間，但對故障排除或分析沒有幫助。它們還可能通過扭曲總數來扭曲分析。這也會引起混淆。
在 OpenTelemetry 文檔中還有更多有用的見解和建議，因此在制定屬性標準時建議查閱最新的規范。
結論
追蹤數據收集是觀測性的一個必要部分。但這需要建立一套流程，以確保數據是有用的、可訪問的，并且具有洞察力。命名規范需要一些前期工作，但通過采納這些最佳實踐 —— 從確保語義清晰和維護統一庫到了解數據、與服務水平保持一致，以及預測新的用例 —— 您的團隊可以提升遙測的效用。
這種方法不僅簡化故障排除，還幫助您在組織內建立一個有效的觀測文化。這項工作的結果是一個充滿可訪問洞察的豐富 OTel 數據集，使更加智能、更加迅速的決策成為可能。
