用途 在需要向 Datadog 查询可观测性数据时使用：搜索日志、查询时序指标、聚合日志统计、列出可用指标或查看指标元数据。pup 是围绕 Datadog API 的命令行封装。
指标 pup metrics query：查询时序指标数据，支持聚合、过滤和分组，是指标分析的主要命令。 pup metrics search：查询语法与 query 相同，但使用更简单的 v1 API，适合不需要 v2 timeseries 公式语义的场景。 pup metrics list：发现可用指标名，可配合 --filter 按模式缩小范围。 pup metrics metadata get：读取指定指标的元数据（描述、单位、类型）。 pup metrics tags list：列出指定指标可用的标签。
日志 pup logs query：使用 v2 API 查询日志（推荐），支持时区和灵活排序。 pup logs search：使用 v1 API 搜索日志，更简单但能力较弱。 pup logs list：以基本过滤列出日志，是最轻量的日志获取方式。 pup logs aggregate：对日志做统计分析，支持 count、avg、percentile、cardinality，并按字段分组。
核心概念 输出格式：-o table 供人阅读，-o json 供机器读取，默认 json。 时间范围：--from 和 --to 接受相对值（1h、30m、7d、1w、1M）或绝对 unix 时间戳，--to 默认是现在。 指标查询语法：<aggregation>:<metric_name>{<filter>} [by {<group>}]。聚合有 avg、sum、min、max、count；过滤为 {env:prod}、{host:web-}、{}；分组如 by {service}、by {host,env}。 日志查询语法：使用 Datadog 搜索语法，可按字段（status:error、service:web-app、host:i-*）、属性（@http.status_code:500）、布尔（AND、OR、NOT、-status:info）、短语（"exact phrase"）和通配符查询。
推荐流程 调查指标：pup metrics list --filter="<pattern>" 发现指标，pup metrics metadata get <metric> 查看单位与类型，pup metrics tags list <metric> 查看维度，再执行 pup metrics query --query="avg:<metric>{<filter>} by {<group>}" --from="1h"。 调查日志：先 pup logs search --query="status:error" --from="1h" --limit=10 看近期错误，再加过滤缩小，然后用 pup logs aggregate --query="status:error" --from="1h" --compute="count" --group-by="service" 找失败服务，最后用 pup logs query 深入查看完整日志。
限制与提示 程序化处理输出时优先 -o json，向用户展示时用 -o table。日志搜索 --limit 默认 50（search 最大 1000，query/list 可配置）。指标查询返回带时间戳的时序数组，数据点在 JSON 的 series 字段中。log aggregate 的 --compute 支持 count、avg(@field)、sum(@field)、min(@field)、max(@field)、cardinality(@field)、percentile(@field, N)，--group-by 可按任意日志字段或属性细分。时间范围相对当前：1h 表示一小时前到现在，7d 表示七天前到现在。使用前需已获得 Datadog 访问凭据；安装与认证方式资料中暂未提供。