🎯Purpose

This demo clarifies two distinct mechanisms for tracking 4xx HTTP errors in Datadog: making a span appear red in APM (error status) vs. creating an actionable Issue in Error Tracking (error details). They are independent — you need both configs to get both behaviors.

The core problem: Datadog's Ruby tracer marks 5xx responses as errors by default — because 5xx means the server failed. But 4xx responses (403 Forbidden, 422 Unprocessable) can also represent business errors worth tracking. There are two separate mechanisms: (1) DD_TRACE_HTTP_SERVER_ERROR_STATUSES marks the span with span.status=1 so it appears red in APM, and (2) span.set_error attaches error.type, error.message, and error.stack — the three tags required for Error Tracking to create an Issue. These are completely separate and each requires its own configuration.

🏗️How It Works — Architecture

Three Ruby/Rack apps, each handling the same 403/422 endpoints with different error configurations. All send traces to a single Datadog Agent on port 8127. Run test.sh to trigger requests to all three simultaneously.

💡Key Concepts

• span.status=1: Marks the span as an error — makes it appear red in APM trace views. Does NOT create an Error Tracking Issue.
• error.type / error.message / error.stack: The three span tags required for Error Tracking to create an Issue. Setting these alone does NOT turn the span red.
• DD_TRACE_HTTP_SERVER_ERROR_STATUSES: Env var — e.g. 400-499,500-599 — that instructs the tracer to set span.status=1 for matching HTTP status codes. Sets status only, no error detail tags.
• span.set_error (Ruby): A tracer method that sets BOTH span.status=1 AND all error.* tags in one call. Full APM + Error Tracking integration.

🚀Quick Start

1. Set your API key:

   echo "DD_API_KEY=your_key_here" > .env

2. Start all services:

   docker compose up -d

3. Run test requests to all three apps:

   bash test.sh

📊What You'll See in Datadog

APM → Traces:

Error Tracking: Only app-for-error-tracking creates Issues. The other two apps generate no Error Tracking Issues, even when spans are red.

🎯目的

4xx HTTPエラーをDatadogで追跡するための2つの異なるメカニズムを明確にします: APMでスパンを赤く表示するか（エラーステータス）、エラートラッキングで対応可能なIssueを作成するか（エラー詳細）。これらは独立しており、両方の動作を得るには両方の設定が必要です。

核心的な問題: DatadogのRubyトレーサーはデフォルトで5xxをエラーとしてマークします。しかし4xx（403 Forbidden、422 Unprocessable）も追跡すべきビジネスエラーになりえます。2つの別々のメカニズムがあります: (1) DD_TRACE_HTTP_SERVER_ERROR_STATUSESはスパンを赤くし、(2) span.set_errorはerror.type・error.message・error.stackを設定してエラートラッキングIssueを作成します。

🏗️仕組み — アーキテクチャ

3つのRuby/Rackアプリ。それぞれ同じ403/422エンドポイントを異なるエラー設定で処理します。すべてポート8127の単一DatadogエージェントにトレースをSendします。test.shで3つすべてにリクエストを送ります。

💡重要な概念

• span.status=1: スパンをエラーとしてマーク — APMで赤く表示されます。エラートラッキングIssueは作成しません。
• error.type / error.message / error.stack: エラートラッキングでIssueを作成するための3つのスパンタグ。これだけではスパンは赤くなりません。
• DD_TRACE_HTTP_SERVER_ERROR_STATUSES: 400-499,500-599などの設定で、該当HTTPステータスコードにspan.status=1を設定します。ステータスのみ設定、エラー詳細タグはなし。
• span.set_error (Ruby): span.status=1とすべてのerror.*タグを一度に設定するトレーサーメソッド。APM + エラートラッキングを完全に統合します。

🚀クイックスタート

1. APIキーを設定:

   echo "DD_API_KEY=your_key_here" > .env

2. 全サービスを起動:

   docker compose up -d

3. 3つのアプリにテストリクエスト:

   bash test.sh

📊Datadogで確認できること

APM → トレース:

エラートラッキング: app-for-error-trackingのみがIssueを作成します。スパンが赤くても、他の2つのアプリはエラートラッキングIssueを作成しません。

🎯目的

本示範釐清在 Datadog 中追蹤 4xx HTTP 錯誤的兩種不同機制：讓 span 在 APM 中顯示為紅色（錯誤狀態）vs. 在 Error Tracking 中建立可操作的 Issue（錯誤詳情）。它們是獨立的——需要兩種設定才能獲得兩種行為。

核心問題：Datadog 的 Ruby tracer 預設將 5xx 回應標記為錯誤，因為 5xx 表示伺服器失敗。但 4xx 回應（403 Forbidden、422 Unprocessable）也可能是值得追蹤的業務錯誤。有兩種獨立機制：(1) DD_TRACE_HTTP_SERVER_ERROR_STATUSES 設定 span.status=1 使 span 在 APM 中顯示為紅色，(2) span.set_error 附加 error.type、error.message 和 error.stack——Error Tracking 建立 Issue 所需的三個標籤。

🏗️運作方式 — 架構

三個 Ruby/Rack 應用程式，每個以不同的錯誤設定處理相同的 403/422 端點。全部向端口 8127 的單一 Datadog Agent 發送追蹤。執行 test.sh 同時向三個應用程式觸發請求。

💡核心概念

• span.status=1：將 span 標記為錯誤——使其在 APM 追蹤視圖中顯示為紅色。不建立 Error Tracking Issue。
• error.type / error.message / error.stack：Error Tracking 建立 Issue 所需的三個 span 標籤。僅設定這些不會使 span 變紅。
• DD_TRACE_HTTP_SERVER_ERROR_STATUSES：環境變數，例如 400-499,500-599，指示 tracer 為匹配的 HTTP 狀態碼設定 span.status=1。僅設定狀態，不設定錯誤詳情標籤。
• span.set_error (Ruby)：在一次呼叫中同時設定 span.status=1 和所有 error.* 標籤的 tracer 方法，完整整合 APM 和 Error Tracking。

🚀快速開始

1. 設定 API 金鑰：

   echo "DD_API_KEY=your_key_here" > .env

2. 啟動所有服務：

   docker compose up -d

3. 向三個應用程式執行測試請求：

   bash test.sh

📊在 Datadog 中會看到什麼

APM → Traces：

Error Tracking：只有 app-for-error-tracking 建立 Issue。即使 span 是紅色的，其他兩個應用程式也不會建立 Error Tracking Issue。