🎯Purpose

This demo shows how Datadog APM handles HTTP 404 responses and why a special naming rule exists to protect your metrics from cardinality explosion.

The core problem: APM traces every request as a "span" with a resource name (e.g. GET /api/users). If a security scanner hits /admin/secret-1, /admin/secret-2, … /admin/secret-999999, and each 404 response kept its original URL path as the resource name, you'd create millions of unique metric series — overwhelming Datadog's metric cardinality limits and making dashboards unusable. The 404 Status Rule solves this by collapsing all 404-returning resources into a single name: "404".

🏗️How It Works — Architecture

The Java Netty app exposes two endpoints. The Datadog Java agent is attached at JVM startup via -javaagent. Every request becomes an APM span. The 404 rule is applied inside the agent before spans are sent to the Datadog Agent on port 8126.

💡Key Concepts

• Resource name: The label Datadog uses to group spans — e.g. GET /api/greeting. This is what appears in the APM resource column.
• Cardinality: The number of unique metric series. Too many unique resource names = too high cardinality = broken dashboards and extra cost.
• DD_TRACE_STATUS404RULE_ENABLED=true (default): All 404 responses get resource name "404" — unlimited unique paths collapse into one.
• DD_TRACE_STATUS404RULE_ENABLED=false: 404 responses keep their original URL path as the resource name. Use this only on controlled internal services.

🚀Quick Start

1. Copy env file:

   cp env.example .env

2. Set your API key in .env:

   DD_API_KEY=your_key_here

3. Build and start:

   docker-compose up -d --build

4. Hit the endpoints:

   curl http://localhost:8080/api/greeting
   curl http://localhost:8080/api/not-found

5. Toggle the rule in .env, rebuild, and compare APM resource names.

📊What You'll See in Datadog

Go to APM → Traces and filter by service:java-404-status-rule.

With rule ON: the 404 resource column shows 404

With rule OFF: the 404 resource column shows GET /api/not-found

🎯目的

DatadogのAPMがHTTP 404レスポンスをどのように扱うか、そしてなぜカーディナリティ爆発を防ぐための特別なルールが存在するかを示します。

核心的な問題: APMは各リクエストをリソース名付きのスパン（例: GET /api/users）として記録します。セキュリティスキャナーが/admin/secret-1〜/admin/secret-999999を叩くと、404レスポンスがそれぞれ固有のリソース名を持ってしまい、メトリクスのカーディナリティが爆発します。404ステータスルールはすべての404リソースを"404"という一つの名前に集約してこれを防ぎます。

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

Java Nettyアプリは2つのエンドポイントを提供します。DatadogのJavaエージェントはJVM起動時に-javaagentで付与されます。すべてのリクエストがAPMスパンになり、404ルールはスパンをポート8126のDatadogエージェントに送信する前にJavaエージェント内で適用されます。

💡重要な概念

• リソース名: Datadogがスパンをグループ化するラベル（例: GET /api/greeting）。APMのリソース列に表示されます。
• カーディナリティ: ユニークなメトリクス系列の数。リソース名が多すぎると高カーディナリティになり、ダッシュボードが壊れたりコストが増加します。
• DD_TRACE_STATUS404RULE_ENABLED=true（デフォルト）: すべての404レスポンスのリソース名が"404"になります。
• DD_TRACE_STATUS404RULE_ENABLED=false: 404レスポンスは元のURLパスをリソース名として保持します。管理された内部サービスでのみ使用してください。

🚀クイックスタート

1. envファイルをコピー:

   cp env.example .env

2. APIキーを設定:

   DD_API_KEY=your_key_here

3. ビルドして起動:

   docker-compose up -d --build

4. エンドポイントにリクエスト:

   curl http://localhost:8080/api/greeting
   curl http://localhost:8080/api/not-found

5. ルールを切り替えてリビルドし、APMのリソース名を比較します。

📊Datadogで確認できること

APM → トレースでservice:java-404-status-ruleでフィルタリングします。

ルールON時: 404のリソース列は 404

ルールOFF時: 404のリソース列は GET /api/not-found

🎯目的

本示範展示 Datadog APM 如何處理 HTTP 404 回應，以及為何需要特殊命名規則來防止指標基數爆炸。

核心問題：APM 將每個請求記錄為帶有資源名稱的 span（例如 GET /api/users）。如果安全掃描器訪問 /admin/secret-1 到 /admin/secret-999999，且每個 404 回應都保留其原始 URL 路徑作為資源名稱，就會產生數百萬個唯一指標序列，使 Datadog 的指標基數超載並讓儀表板無法使用。404 狀態規則將所有 404 資源折疊為單一名稱 "404" 來解決這個問題。

🏗️運作方式 — 架構

Java Netty 應用程式提供兩個端點。Datadog Java agent 在 JVM 啟動時透過 -javaagent 附加。每個請求都成為 APM span。404 規則在 span 發送到端口 8126 的 Datadog Agent 之前，在 Java agent 內部應用。

💡核心概念

• 資源名稱：Datadog 用來分組 span 的標籤，例如 GET /api/greeting，顯示在 APM 資源欄中。
• 基數（Cardinality）：唯一指標序列的數量。太多唯一資源名稱 = 基數過高 = 儀表板崩潰且成本增加。
• DD_TRACE_STATUS404RULE_ENABLED=true（預設）：所有 404 回應的資源名稱變為 "404"。
• DD_TRACE_STATUS404RULE_ENABLED=false：404 回應保留其原始 URL 路徑作為資源名稱。僅在受控的內部服務中使用。

🚀快速開始

1. 複製環境檔案：

   cp env.example .env

2. 設定 API 金鑰：

   DD_API_KEY=your_key_here

3. 建置並啟動：

   docker-compose up -d --build

4. 訪問端點：

   curl http://localhost:8080/api/greeting
   curl http://localhost:8080/api/not-found

5. 在 .env 中切換規則，重新建置，比較 APM 資源名稱。

📊在 Datadog 中會看到什麼

前往 APM → Traces，以 service:java-404-status-rule 篩選。

規則 開啟時：404 資源欄顯示 404

規則 關閉時：404 資源欄顯示 GET /api/not-found