Datadog APM测试代理

APM测试代理是一个应用程序，它模拟了Datadog代理的APM端点，可用于测试Datadog APM客户端库。

有关提供的完整功能列表，请参阅功能部分。

有关可用端点，请参阅HTTP API部分。

有关如何在本地运行测试代理以添加额外检查或修复错误，请参阅开发部分。

安装

测试代理可以从PyPI

pip install ddapm-test-agent

ddapm-test-agent --port=8126

或从Docker

# Run the test agent and mount the snapshot directory
docker run --rm\
        -p 8126:8126\
        -e SNAPSHOT_CI=0\
        -v $PWD/tests/snapshots:/snapshots\
        ghcr.io/datadog/dd-apm-test-agent/ddapm-test-agent:latest

或从源

pip install git+https://github.com/Datadog/dd-apm-test-agent

或特定分支安装

pip install git+https://github.com/Datadog/dd-apm-test-agent@{branch}

功能

跟踪不变性检查

测试代理提供了许多检查，用于验证跟踪数据。默认情况下，所有检查都已启用，并可手动禁用。

有关选项，请参阅配置部分。

返回数据

可以检索提交给测试代理的所有数据。

• 可以通过以下以下记录的/test/traces端点返回跟踪。

有用的日志记录

测试代理的INFO日志级别会输出测试代理接收到的请求的有用信息。对于跟踪，这包括跟踪的可视化表示。

INFO:ddapm_test_agent.agent:received trace payload with 1 trace chunk
INFO:ddapm_test_agent.agent:Chunk 0
[parent]
├─ [child1]
├─ [child2]
└─ [child3]
INFO:ddapm_test_agent.agent:end of payload ----------------------------------------

代理

测试代理为Datadog代理提供代理功能。这可以通过将代理URL传递给测试代理来启用，无论是通过--agent-url命令行参数，还是通过DD_TRACE_AGENT_URL或DD_AGENT_URL环境变量。

当代理启用时，将返回来自Datadog代理的响应，而不是来自测试代理的响应。

在跟踪级别，也可以通过包含带有值为true的X-Datadog-Agent-Proxy-Disabled头禁用代理。这将禁用代理，无论是否设置了代理URL。

快照测试

测试代理提供了一种我们称之为快照的特征测试形式。这允许库维护者确保在做出不相关的更改时，跟踪不会意外更改。

这可以通过让测试用例使用追踪器发出跟踪，并由测试代理收集并与之前存储的参考跟踪进行比较来实现。

使用测试代理进行快照测试

1. 确保跟踪与一个会话令牌（通常是测试用例的名称）相关联，可以通过以下方式之一：
   • 在发出跟踪之前调用/test/session/start，并带有令牌端点；或
   • 在/vX.Y/trace请求上附加额外的查询字符串参数或头指定会话令牌（以下为API具体信息）。 (必需以并发运行测试)
2. 发出跟踪（运行集成测试）。
3. 通过调用带有会话令牌的/tests/session/snapshot端点来通知会话结束并执行快照比较。如果快照失败，则端点将返回400响应代码，以及一个纯文本错误跟踪，该错误可以转发给测试框架以帮助分类问题。

快照输出

跟踪被标准化并以JSON格式输出到文件。对输入执行以下转换：

• 覆盖跟踪ID以匹配接收到的跟踪顺序。
• 覆盖跟踪ID以匹配跟踪树中跟踪的DFS顺序。
• 使用标准化后的跟踪ID覆盖父ID。但是，如果父ID不是跟踪中的跟踪，则不会覆盖父ID。这对于处理分布式跟踪是必要的，其中并非所有跟踪都发送到同一个代理。
• 对跟踪属性进行排序，以便更易于阅读，重要的属性列在前面。
• 否则按字母数字顺序对跟踪属性进行排序。
• 如果空，则排除跟踪元数据和度量映射。

配置

可以通过命令行选项或通过环境变量来配置测试代理。

命令行

ddapm-test-agent

ddapm-test-agent是用于运行测试代理的命令。

请参阅ddapm-test-agent --help获取更多信息。

ddapm-test-agent-fmt

ddapm-test-agent-fmt是一个命令行工具，用于格式化或检查快照JSON文件。

# Format all snapshot json files
ddapm-test-agent-fmt path/to/snapshots

# Lint snapshot json files
ddapm-test-agent-fmt --check path/to/snapshots

请参阅ddapm-test-agent-fmt --help获取更多信息。

环境变量

• PORT [8126]: 监听的端口。

• ENABLED_CHECKS [""]: 要启用的检查的逗号分隔值。有效值可以在跟踪不变性检查中找到。

• LOG_LEVEL ["INFO"]: 要使用的日志级别。DEBUG、INFO、WARNING、ERROR、CRITICAL。

• LOG_SPAN_FMT ["[{name}]"]: 输出日志中的跟踪时使用的格式字符串。

• SNAPSHOT_DIR ["./snapshots"]: 存储快照的目录。可以通过在 /snapshot 上提供 dir 查询参数来覆盖。

• SNAPSHOT_CI [0]: 切换快照测试的 CI 模式。设置为 1 以启用。CI 模式执行以下操作

  • 当意外地从测试用例中生成快照时，将引发失败。

• SNAPSHOT_IGNORED_ATTRS ["span_id,trace_id,parent_id,duration,start,metrics.system.pid,metrics.process_id,metrics.system.process_id,meta.runtime-id"]: 在快照中比较跨度时忽略的属性。

• DD_AGENT_URL [""]: Datadog 代理的 URL。当提供时，请求将被代理到代理。

• DD_APM_RECEIVER_SOCKET [""]: 当提供时，测试代理将在提供的路径上监听跟踪（例如，/var/run/datadog/apm.socket）

• DD_SUPPRESS_TRACE_PARSE_ERRORS [false]: 设置为 "true" 以禁用解码处理跟踪时的跨度解析错误。当禁用时，错误不会抛出，即使度量值错误地放置在元字段中，或者与跨度标记格式/类型相关的其他类型错误。也可以使用 --suppress-trace-parse-errors=true 选项设置。

• SNAPSHOT_REMOVED_ATTRS [""]: 从快照中的跨度中删除的属性。这对于删除与测试用例无关的属性很有用。**注意，不允许删除 span_id 以维护跨度排序。**

• DD_POOL_TRACE_CHECK_FAILURES [false]: 设置为 "true" 以在 Test-Agent 内存中池化 Trace Check 失败。可以使用 /test/trace_check/failures 端点稍后查询这些失败。也可以使用 --pool-trace-check-failures=true 选项设置。

• DD_DISABLE_ERROR_RESPONSES [false]: 设置为 "true" 以在 Trace Check 失败时禁用 Test-Agent <Response 400>，而是发送有效的 <Response 200>。建议与 DD_POOL_TRACE_CHECK_FAILURES 环境变量一起使用。也可以使用 --disable-error-responses=true 选项设置。

HTTP API

/test/traces

返回代理收到的跟踪。可以使用以下选项请求与特定跟踪 ID 匹配的跟踪。

[可选] ?trace_ids=

[可选] X-Datadog-Trace-Ids

将跟踪 ID 指定为逗号分隔的值（例如，12345,7890,2468）

/test/session/start

启动一个 同步 会话。随后接收的所有跟踪都将与提供的所需测试令牌相关联。

[可选] ?agent_sample_rate_by_service=

代理在响应 v0.4 和 v0.5 请求时返回的采样率。

示例："{'service:test,env:staging': 0.5, 'service:test2,env:prod': 0.2}"（注意 JSON 必须进行 URL 编码）。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

测试用例的测试会话令牌。**确保此值是唯一的，以避免会话之间的冲突。**

/test/session/snapshot

在会话期间执行数据生成或比较快照。

当测试代理不在 CI 模式下并且没有快照文件时，将生成快照。否则将执行快照比较。

[可选*] ?test_session_token=

[可选*] X-Datadog-Test-Session-Token

为了并行运行测试用例，必须指定此 HTTP 标头。所有共享测试令牌的测试用例将被分组。

* 必需用于并发测试。可以通过查询参数或 HTTP 标头进行。

[可选] ?ignores=

要忽略的值的键的逗号分隔列表。

默认内置忽略列表为：span_id、trace_id、parent_id、duration、start、metrics.system.pid、metrics.process_id、metrics.system.process_id、meta.runtime-id。

[可选] ?dir=

默认：./snapshots（相对于测试代理运行的位置）。

覆盖存储和检索快照的目录。 此目录必须已存在。

此值将覆盖环境变量 SNAPSHOT_DIR。

警告：指定 dir 和 file 两者是错误的。

[可选] ?file=

[可选] X-Datadog-Test-Snapshot-Filename

将存储和检索快照的绝对或相对（相对于代理当前工作目录）文件名。

警告：指定 file 和 dir 两者是错误的。

注意：文件扩展名将被附加到文件名。

对于跟踪统计请求，将向文件名附加 _tracestats。

[可选] ?removes=

要从快照中的跨度中删除的键的逗号分隔列表。

默认的内置删除列表不删除任何键。

/test/session/requests

返回代理接收到的给定会话令牌的所有请求。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

以以下 json 格式返回请求

[
  {
    "headers": {},
    "body": "...",
    "url": "http...",
    "method": "GET"
  }
]

body 是请求的 base64 编码正文。

/test/session/traces

返回代理接收到的给定会话令牌的跟踪。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

/test/session/stats

返回代理接收到的给定会话令牌的统计数据。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

统计数据以接收到的统计数据有效负载的 JSON 列表形式返回。

/test/session/responses/config (POST)

创建用于在端点 /v0.7/config 检索的远程配置有效负载。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

curl -X POST 'http://0.0.0.0:8126/test/session/responses/config/path' -d '{"roots": ["eyJ....fX0="], "targets": "ey...19", "target_files": [{"path": "datadog/2/ASM_DATA/blocked_users/config", "raw": "eyJydWxlc19kYXRhIjogW119"}], "client_configs": ["datadog/2/ASM_DATA/blocked_users/config"]}'

/test/session/responses/config/path (POST)

由于远程配置有效负载相当复杂，此端点类似于 /test/session/responses/config (POST)，但您应发送路径和消息，然后此端点构建远程配置有效负载。

JSON 正文的键是 path 和 msg

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

curl -X POST 'http://0.0.0.0:8126/test/session/responses/config/path' -d '{"path": "datadog/2/ASM_DATA/blocked_users/config", "msg": {"rules_data": []}}'

/test/trace_check/failures (GET)

获取发生的跟踪检查失败。如果包含令牌，则返回该会话令牌的跟踪失败，除非与 return_all 一起使用，后者可以用于返回所有失败，无论输入的令牌是什么。如果没有返回跟踪检查失败，则此方法返回 <Response 200>，如果返回跟踪检查失败，则返回 <Response 400>。跟踪检查失败作为文本内容类型返回，失败消息连接在响应正文。可选地，将 use_json 查询字符串参数设置为 true 以将跟踪检查失败作为以下格式的 JSON 响应返回

response = { 
  "<FAILING_CHECK_NAME>" : ["<FAILURE_MESSAGE_1>", "<FAILURE_MESSAGE_2>"]
}

注意：应与 DD_POOL_TRACE_CHECK_FAILURES 一起使用，否则失败将不会在测试代理内存中保存，并且将始终返回 <Response 200>。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

[可选] ?use_json=

[可选] ?return_all=

curl -X GET 'http://0.0.0.0:8126/test/trace_check/failures'

/test/trace_check/clear (GET)

清除发生的跟踪检查失败。如果包含令牌，则清除该会话令牌的跟踪失败，除非与 clear_all 一起使用。此参数可以用于清除所有失败（无论输入的会话令牌是什么）。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

[可选] ?clear_all=

curl -X GET 'http://0.0.0.0:8126/test/trace_check/clear'

/test/trace_check/summary (GET)

获取跟踪检查摘要结果。如果包含令牌，则仅返回会话期间运行的跟踪检查的摘要结果。可以使用 return_all 可选查询字符串参数返回所有跟踪检查结果（无论输入的会话令牌是什么）。此方法以以下 JSON 格式返回跟踪检查结果

summary = { 
  "trace_content_length" : {
    "Passed_Checks": 10,
    "Failed_Checks": 0,
    "Skipped_Checks": 4,
  }  ...
}

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

[可选] ?return_all=

curl -X GET 'http://0.0.0.0:8126/test/trace_check/summary'

/test/session/integrations (PUT)

更新当前测试集成信息。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

curl -X PUT 'http://0.0.0.0:8126/test/session/integrations' -d '{"integration_name": [INTEGRATION_NAME], "integration_version": [INTEGRATION_VERSION],
"dependency_name": [DEPENDENCY_NAME], "tracer_language": [TRACER_LANGUAGE], "tracer_version": [TRACER_VERSION]}'

/test/integrations/tested_versions (GET)

返回代理接收到的所有测试集成的逗号分隔列表。返回数据格式为：tracer_language,tracer_version,integration_name,integration_version,dependency_name。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

curl -X GET 'http://0.0.0.0:8126/test/integrations/tested_versions'

/v0.1/pipeline_stats

模仿代理的 pipeline_stats 端点，但总是返回 OK，并在每次调用时记录一行。

/tracer_flare/v1

模拟代理的tracer_flare端点。如果焰火包含所需的表单字段，则返回OK，否则返回400。

每次调用时记录一行日志，并将tracer焰火详细信息存储在请求中的"_tracer_flare"下。

/test/session/tracerflares

返回代理收到的给定会话令牌的所有tracer-flares。

[可选] ?test_session_token=

[可选] X-Datadog-Test-Session-Token

以下JSON格式返回tracer-flares

[
  {
    "source": "...",
    "case_id": "...",
    "email": "...",
    "hostname": "...",
    "flare_file": "...",
  }
]

flare_file是tracer-flare有效负载的base64编码内容。

如果解析tracer-flare表单时出现错误，将在error下记录。

开发

先决条件

需要Python 3.8或更高版本和riot。建议创建并使用虚拟环境。

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e '.[testing]'

运行测试

要运行测试（在Python 3.12中）

riot run -p3.12 test

注意：如果需要在测试集中（重新）生成快照，请设置环境变量GENERATE_SNAPSHOTS=1。

GENERATE_SNAPSHOTS=1 riot run --pass-env -p3.12 test -k test_trace_missing_received

代码风格和格式化

要检查代码风格、格式和类型

riot run -s flake8
riot run -s fmt
riot run -s mypy

Docker

构建（并标记）Dockerfile

docker build --tag testagent .

运行标记的镜像

docker run --rm -v ${PWD}/snaps:/snapshots --publish 8126:8126 agent

发行说明

本项目遵循semver，因此必须为错误修复、重大更改、新功能等编写发行说明。要生成发行说明

riot run reno new <short-description-of-change>

在生成的文件中记录更改，删除不相关的部分，并与更改一起提交发行说明。

发布

1. 检出master分支并确保其是最新的。

    git checkout master && git pull

2. 生成发行说明并使用pandoc格式化它们以供Github使用

    riot run -s reno report --no-show-source | pandoc -f rst -t gfm --wrap=none

将输出复制到新发行版：https://github.com/DataDog/dd-apm-test-agent/releases/new。

2. 输入发布标签（遵循semver）（例如，v1.1.3、v1.0.3、v1.2.0）。
3. 使用不带v的标签作为标题。
4. 将发布保存为草稿并将链接传递给其他人进行快速审查。
5. 如果一切正常，请点击发布