主机代理 REST API

基础设施的相关性 Linux

来自主机代理 1.1.582 ，如果满足以下前提条件，主机代理接收到的度量和跟踪数据将与发送数据的进程相关联：

• 主机代理在 Linux 系统上运行，可使用以下命令： lsns, nsenter, 和 ss。
• 发送度量和跟踪数据的进程与主机代理运行在同一主机上。
• 使用忽略进程功能不会忽略发送指标和跟踪数据的进程。
• 指标和跟踪会直接报告给主机代理，而不是代理（例如，使用 OpenTelemetry Collector 的 OpenTelemtry ）。 如果度量和跟踪数据通过代理传输，代理进程将与度量和跟踪数据关联。

对于跟踪数据，应用程序视角服务仪表板可正确引用摄取相关跟踪的任何流程，例如包括该服务发生的基础架构变更。

如果其中任何一个前提条件未满足，指标和跟踪数据将与运行主机代理的主机相关联。

对于相应 API 的后续调用，强烈建议您重复使用与代理的 API 端点建立的连接。 否则，将针对每个新的 API 请求触发进程查找。 如果无法保证这一点，并且遇到问题（例如，高跟踪率的高负载场景），可以禁用进程查询。 来自应用程序接口的度量和跟踪仍将与采集数据的主机相关联，但不会与相应的流程实体相关联。

要禁用进程查询，请在代理的 configuration.yaml 文件中添加以下代码段：

com.instana.processlookup:
  enabled: false

OpenTelemetry 度量和跟踪终端

有关 OpenTelemetry 指标和跟踪摄取，请参阅 OpenTelemetry 文档。

Prometheus 度量终端

有关 Prometheus 指标摄取，请参阅 Prometheus 远程写入文档。

事件 SDK Web 服务

终点： http://<agent_ip>:42699/com.instana.plugin.generic.event

通过使用事件 SDK REST 网络服务，您可以将自定义健康检查和其他事件源集成到 Instana 中。 每一个都在用于输入手动事件的 Instana 代理上运行。 该代理有一个端点，其监听地址为 http://<agent_ip>:42699/com.instana.plugin.generic.event ，例如接受以下带有 POST 请求的 JSON：

{
  "title": <string>,
  "text": <string>,
  "severity": <integer>,
  "timestamp": <integer>,
  "duration": <integer>,
}

以下事件参数可用：

• 标题 ：Instana 事件视图中显示的标题。

• 文本 ：事件详情部分显示的描述。

• severity：可选整数，为以下值之一，具体取决于预期的事件类型。

  • 变更事件：-1（缺省值）
  • 警告事件：5
  • 紧急事件：10

  此外，如果标题字段包含关键字 "online" 或 "offline"，那么会将变更事件视为存在事件。

• 时间戳 ：事件的时间戳（ 毫秒），从 UNIX 时间开始计算。 如果不存在，则改用当前时间。

• duration：可选的事件持续时间（毫秒）。 如果未指定值，事件将显示为无持续时间的 "即时 "事件。 此外，"变化 "事件或 "存在 "事件总是在持续时间结束后关闭。 要延长事件的持续时间，可使用 path 参数确定一个开放事件，该事件的值与 path 参数设置的值相同。

• incident：可选 boolean 将其设置为 Incident 触发事件（如果设置为 true）。 这就要求 severity 具有积极性。

• path：可选标识符，在可能需要使用相同路径值通过对该端点的后续请求扩展事件时，可定义该标识符。

下面的示例显示了一个即时事件：

{
    "title": "Instant critical event on the host",
    "text": "Description of the event that occurred",
    "severity": 10
}

下面的示例显示了一个持续时间为 5 分钟的事件，使用 path 参数可以延长该事件的持续时间。 如果没有发送具有相同 path 标识符的后续事件，事件将在 5 分钟后自动关闭：

{
    "title": "WARNING: This event started to happen",
    "text": "It will be active for 5 minutes",
    "severity": 5,
    "duration": 300000,
    "path": "unique-event-identifier"
}

您可以使用相同的 path 参数发送后续事件，以延长事件的有效期。 下面的示例事件将上一个示例中的事件延长了 5 分钟：

{
    "title": "WARNING: This event continues to happen",
    "text": "It will be active for another 5 minutes",
    "severity": 5,
    "duration": 300000,
    "path": "unique-event-identifier"
}

在指定数组时，端点也接受批量事件：

[
  {
    "title": "First event",
    ...
  },
  {
    "title": "Second event",
    ...
  }
]

duration = (Time.now.to_f * 1000).floor - deploy_start_time_in_ms
payload = {}
payload[:title] = 'Deployed MyApp'
payload[:text] = 'pglombardo deployed MyApp@revision'
payload[:duration] = duration

uri = URI('http://localhost:42699/com.instana.plugin.generic.event')
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req.body = payload.to_json
Net::HTTP.start(uri.hostname, uri.port) do |http|
  http.request(req)
end

curl -XPOST http://localhost:42699/com.instana.plugin.generic.event -H "Content-Type: application/json" -d '{"title":"Custom API Events ", "text": "Failure Redeploying Service Duration", "duration": 60000, "severity": 5}'

Invoke-RestMethod
	-Uri http://localhost:42699/com.instana.plugin.generic.event
	-Method POST
	-Body '{"title":"PowerShell Event ", "text": "You used PowerShell to create this event!", "severity": -1}'

Invoke-WebRequest
  -Uri http://localhost:42699/com.instana.plugin.generic.event
  -Method Post
  -Body '{"title":"PowerShell Event ", "text": "You used PowerShell to create this event!", "severity": -1}'

跟踪 SDK Web 服务

终点： http://<agent_ip>:42699/com.instana.plugin.generic.trace

使用跟踪 SDK REST Web 服务，可以将 Instana 集成到任何应用程序，而无需考虑所用的语言。 每个活动 Instana 代理都可用于将手动捕获的跟踪馈送到 Web 服务，此 Web 服务既可以与自动捕获的跟踪相结合，也可以保持完全独立。 代理提供的端点监听 http://<agent_ip>:42699/com.instana.plugin.generic.trace URL ，并通过 POST 请求接受以下 JSON：

{
  "spanId": <string>,
  "parentId": <string>,
  "traceId": <string>,
  "timestamp": <64 bit long>,
  "duration": <64 bit long>,
  "name": <string>,
  "type": <string>,
  "error": <boolean>,
  "data": {
    <string> : <string>
  }
}

spanId 是任何特定跨度的唯一标识符。 跟踪由根跨度定义，即没有 parentId 的跨度。 对于属于同一轨迹的所有跨度， traceId 必须相同，并允许与 spanId 重叠。 traceId, spanId, 和 parentId 是以十六进制字符串编码的 64 位唯一值，如 b0789916ff8f319f。 跨度通过将父级的 spanId 引用为 parentId 可形成层次结构。跟踪中的跨度层次结构示例如下：

	root (spanId=1, traceId=1, type=Entry)
	  child A (spanId=2, traceId=1, parentId=1, type=Exit)
	    child A (spanId=3, traceId=1, parentId=2, type=Entry)
	      child B (spanId=4, traceId=1, parentId=3, type=Exit)
	child B (spanId=5, traceId=1, parentId=4, type=Entry)

timestamp 和 duration 字段以毫秒为单位。 时间戳记必须是与全球标准时间协调的戳记时间戳记。

name 字段可以是用于对跟踪进行可视化和分组的任何字符串，并且可以包含任何文本。 但是，建议尽量简洁。

type 字段为可选字段，如果不存在，则视为 ENTRY。 选项包括 ENTRY、EXIT、INTERMEDIATE 或 EUM。 设置类型对于 UI 而言至关重要。 假设在 ENTRY 之后，子级跨度为 INTERMEDIATE 或 EXIT。 EXIT 之后， ENTRY 。 我们可以将其显示为一个远程调用。

data 字段为可选字段，可以包含任意的键值对。 未指定提供重复键的行为。

error 字段为可选字段，可以设置为 true 以指示错误的跨度。

端点也可以接受批量跨度，此类跨度需要作为数组提供：

[
  {
    // span as above
  },
  {
    // span as above
  }
]

对于通过使用跟踪 SDK Web 服务接收的跟踪，与转换和服务/端点命名相关的规则与 Java 跟踪 SDK 相同。 data 中的这些键值对尤其用于命名： service, endpoint, 和 call.name。

Kubernetes 上提供的可选 Instana 代理服务与 Instana 代理 Helm Chart 结合使用，对 Trace Web SDK 支持非常有用。 这是因为它能确保数据被推送到运行在同一 Kubernetes 节点上的 Instana 代理，并确保 Instana 代理能正确填写基础设施相关数据。

#!/bin/bash

curl -0 -v -X POST 'http://localhost:42699/com.instana.plugin.generic.trace' -H 'Content-Type: application/json; charset=utf-8' -d @- <<EOF
[
  {
    "spanId": "8165b19a37094800",
    "traceId": "1368e0592a91fe00",
    "timestamp": 1591346182000,
    "duration": 134,
    "name": "GET /my/service/asdasd",
    "type": "ENTRY",
    "error": false,
    "data": {
      "http.url": "https://orders.happyshop.com/my/service/asdasd",
      "http.method": "GET",
      "http.status_code": 200,
      "http.path": "/my/service/asdasd",
      "http.host": "orders.happyshop.com"
    }
  },
  {
    "spanId": "7ddf6b31b320cc00",
    "parentId": "8165b19a37094800",
    "traceId": "1368e0592a91fe00",
    "timestamp": 1591346182010,
    "duration": 97,
    "name": "GET /orders/asdasd",
    "type": "EXIT",
    "error": false,
    "data": {
      "http.url": "https://crm.internal/orders/asdasd",
      "http.method": "GET",
      "http.status_code": 200,
      "http.path": "/orders/asdasd",
      "http.host": "crm.internal"
    }
  }
]
EOF