菜单
文档breadcrumb arrow Grafana Tempobreadcrumb arrow APIbreadcrumb arrow 使用 HTTP 推送 Span
开源

使用 HTTP 推送 Span

有时使用追踪系统会令人望而却步，因为它似乎需要复杂的应用程序插桩或 Span 摄取管道才能推送 Span。本指南旨在展示一种使用 Bash 脚本通过 HTTP/JSON 推送 Span 的极其基础的技术，该技术使用 OpenTelemetry 接收器。

开始之前

此过程使用示例 Docker Compose 设置来运行 Tempo，因此你不需要已有的安装。该 Docker 镜像还包含一个 Grafana 容器，允许你可视化追踪。

要使用此过程，你需要安装 Docker 和 docker compose。

使用快速入门启动 Tempo

使用Tempo 快速入门文档中的说明，启动一个本地 Tempo 和 Grafana 实例。

使用 OTLP 推送 Span

现在 Tempo 正在运行并监听端口 4318 以接收 OTLP Span，让我们使用 curl 向其推送一个 Span。

在使用此示例之前，你需要按照指示更新开始时间和结束时间。

bash 
curl -X POST -H 'Content-Type: application/json' https://:4318/v1/traces -d '
{
	"resourceSpans": [{
    	"resource": {
        	"attributes": [{
            	"key": "service.name",
            	"value": {
                	"stringValue": "my.service"
            	}
        	}]
    	},
    	"scopeSpans": [{
        	"scope": {
            	"name": "my.library",
            	"version": "1.0.0",
            	"attributes": [{
                	"key": "my.scope.attribute",
                	"value": {
                    	"stringValue": "some scope attribute"
                	}
            	}]
        	},
        	"spans": [
        	{
            	"traceId": "5B8EFFF798038103D269B633813FC700",
            	"spanId": "EEE19B7EC3C1B100",
            	"name": "I am a span!",
            	"startTimeUnixNano": 1689969302000000000,
            	"endTimeUnixNano": 1689970000000000000,
            	"kind": 2,
            	"attributes": [
            	{
                	"key": "my.span.attr",
                	"value": {
                    	"stringValue": "some value"
                	}
            	}]
        	}]
    	}]
	}]
}'

请注意，startTimeUnixNano 字段以纳秒为单位，可以通过任何提供纪元日期（以纳秒为单位）的工具获取（例如，在 Linux 下，date +%s%N）。endTimeUnixNano 字段也以纳秒为单位，其中 100000000 纳秒是 100 毫秒。

  1. 将 curl 命令复制并粘贴到文本编辑器中。

  2. 将 startTimeUnixNano 和 endTimeUnixNano 替换为过去 24 小时内的当前值，以便你可以使用 24 小时相对时间范围搜索它们。你可以从以下链接获取秒和毫秒值。将毫秒值乘以 1,000,000 转换为纳秒。你可以在 bash 终端中使用以下命令完成此操作

    bash 
    echo $((<epochTimeMilliseconds> * 1000000))

  3. 将更新后的 curl 命令复制到终端窗口并运行它。

  4. 在 Grafana 中查看追踪

    1. 在浏览器中打开 https://:3000。
    2. 打开 Explorer 页面并选择 Tempo 数据源。
    3. 选择 Search 查询类型。
    4. 选择 Run query 列出可用的追踪。
    5. 选择追踪 ID（黄色框）以查看追踪及其 Span 的详细信息。

Using the TraceQL query builder on Explore to view pushed trace in Grafana.

检索追踪

获取追踪的最简单方法是向 Tempo 执行一个简单的 curl 命令。返回的格式是 OTLP。

  1. 将 curl 命令中的追踪 ID 替换为推送生成的追踪 ID。这些信息包含在随 curl 发送的数据中。你可以使用 Grafana 的 Explorer 页面找到它，如上一节所示。

    bash 
    curl https://:3200/api/v2/traces/5b8efff798038103d269b633813fc700

{"trace": {"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"my.service"}}]},"scopeSpans":[{"scope":{"name":"my.library","version":"1.0.0"},"spans":[{"traceId":"W47/95gDgQPSabYzgT/HAA==","spanId":"7uGbfsPBsQA=","name":"I am a span!","kind":"SPAN_KIND_SERVER","startTimeUnixNano":"1689969302000000000","endTimeUnixNano":"1689970000000000000","attributes":[{"key":"my.span.attr","value":{"stringValue":"some value"}}],"status":{}}]}]}]}}

  2. 将更新后的 curl 命令复制并粘贴到终端窗口中。

使用 TraceQL 搜索追踪

或者，你也可以使用 TraceQL 搜索已推送的追踪。你可以通过设置的唯一追踪属性进行搜索

bash 
curl -G -s https://:3200/api/search --data-urlencode 'q={ .service.name = "my.service" }'

{"traces":[{"traceID":"5b8efff798038103d269b633813fc700","rootServiceName":"my.service","rootTraceName":"I am a span!","startTimeUnixNano":"1694718625557000000","durationMs":10000,"spanSet":{"spans":[{"spanID":"eee19b7ec3c1b100","startTimeUnixNano":"1694718625557000000","durationNanos":"10000000000","attributes":[{"key":"service.name","value":{"stringValue":"my.service"}}]}],"matched":1},"spanSets":[{"spans":[{"spanID":"eee19b7ec3c1b100","startTimeUnixNano":"1694718625557000000","durationNanos":"10000000000","attributes":[{"key":"service.name","value":{"stringValue":"my.service"}}]}],"matched":1}]}],"metrics":{"inspectedBytes":"292781","completedJobs":1,"totalJobs":1}}

要以更具可读性的输出格式化此内容，可以考虑使用jq 之类的工具，它允许你运行相同的 curl 命令并将其通过管道传递给 jq 来格式化数据块。例如

bash 
curl -G -s https://:3200/api/search --data-urlencode 'q={ .service.name = "my.service" }' | jq

来自一切的 Span

追踪不仅限于使用复杂框架的企业级语言。如你所见，存储和跟踪来自你的 js、python 或 bash 脚本的事件非常容易。你今天就可以使用 Tempo 和分布式追踪来追踪 CI 流水线、长时间运行的 bash 进程、python 数据处理流程，或者你能想到的任何其他内容。

愉快地追踪！