主機代理程式 REST API

Linux

從主機代理程式 1.1.582開始，如果符合下列前置條件，則主機代理程式所接收的度量及追蹤資料會與傳送資料的處理程序產生關聯:

1. 主機代理程式正在 Linux 系統上執行，並具有下列可用指令: lsns、 nsenter及 ss。
2. 傳送度量及追蹤資料的處理程序正在與主機代理程式相同的主機上執行。
3. 使用 忽略處理程序 功能不會忽略傳送度量及追蹤資料的處理程序。
4. 度量值和追蹤資料會直接報告給主機代理程式，而不是透過 Proxy 執行 (例如，針對使用 OpenTelemetry Collector的 OpenTelemtry )。 如果度量及追蹤資料通過 Proxy ，則 Proxy 處理程序會改為與度量及追蹤相關聯。

對於追蹤資料，「應用程式視景服務」儀表板會正確地參照從中汲取相關追蹤資料的任何處理程序，例如，針對此服務發生的基礎架構變更。

如果未滿足其中任何前置條件，則度量和追蹤資料會與主機代理程式執行所在的主機產生關聯。

附註: 對於後續的對應 API 呼叫，強烈建議您對代理程式的 API 端點重複使用建立一次的連線。 否則，會針對每個新的 API 要求觸發程序查閱。 如果無法保證這樣做，且您遇到問題 (例如，高追蹤率的高負載實務範例) ，則可以停用程序查閱。 來自 API 的度量值和追蹤資料仍會與汲取資料的主機產生關聯，但不會與對應的程序實體產生關聯。 若要停用程序查閱，請將下列 Snippet 新增至代理程式的 configuration.yaml 檔案:

com.instana.processlookup:
  enabled: false

OpenTelemetry 度量及追蹤端點

如需 OpenTelemetry 度量值及追蹤汲取，請參閱 OpenTelemetry 文件。

附註: Instana 中的 OpenTelemetry 支援在技術預覽中，且正在努力讓 OpenTelemetry 成為與 Instana 自己的 AutoTrace 技術具有完整交互作業能力的一流公民!

Prometheus 度量值端點

如需 Prometheus 度量汲取，請參閱 Prometheus 遠端寫入文件。

事件 SDK Web 服務

端點: http://<agent_ip>:42699/com.instana.plugin.generic.event

透過使用事件 SDK REST Web 服務，可以將自訂性能檢查及其他事件來源整合至 Instana。 執行 Instana 代理程式的每一個 Web 服務都可用來手動輸入事件。 代理程式具有在 http://<agent_ip>:42699/com.instana.plugin.generic.event 上接聽並接受 (例如，具有 POST 要求的下列 JSON) 的端點:

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

可以使用下列事件參數：

• title: Instana 事件視圖中顯示的標題。

• text: 事件的詳細資料區段中顯示的說明。

• severity：選用的整數，視想要的事件類型而定，會有下列其中一值：

  • 變更事件：-1（預設值）
  • 警告事件：5
  • 重大事件：10

  再者，如果 title 欄位含有 "online" 或 "offline" 關鍵字，會將變更事件視為存在事件。

• timestamp: 事件的時間戳記，以 自 UNIX 新紀元以來的毫秒數為單位。 如果不存在，則會改用現行時間。

• duration：（選用）事件的持續時間（毫秒）。 如果未指定值，則事件會顯示為沒有持續時間的「即時」事件。 此外，「變更」事件或「存在」事件一律在持續時間之後關閉。 若要延長事件的持續時間，請使用 path 參數來識別與 path 參數上所設定值相同的開啟事件。

• incident: 選用 布林 ，如果設為 true，則會將它轉換為 發生事件 觸發事件。 這需要 severity 是正數。

• path：選用 ID，在可能需要使用相同的 path 值對此端點的後續要求延伸事件時，可以定義此 ID。

下列範例顯示即時事件:

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

下列範例顯示持續時間為 5 分鐘的事件，可以使用 path 參數進行延伸。 如果未傳送任何具有相同 path ID 的後續事件，則事件會在 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 是任何特定跨距的唯一 ID。 追蹤由根跨距定義，亦即沒有 parentId 的跨距。 對於屬於相同追蹤且容許與 spanId重疊的所有文字段， traceId 必須相同。 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 欄位以毫秒為單位。 時間戳記必須是與「世界標準時間 (UTC)」協調的新紀元時間戳記。

name 欄位可以是用來視覺化及分組追蹤資料的任何字串，並且可以包含任何文字。 不過，建議使用簡單字串。

type 欄位是選用的，如果不存在，則會將其視為 ENTRY。 選項為 ENTRY、EXIT、INTERMEDIATE 或 EUM。 設定類型對於使用者介面而言很重要。 假設在 ENTRY 之後，子項跨距為 INTERMEDIATE 或 EXIT。 在 EXIT之後，接著 ENTRY 。 可以將此視為一個遠端呼叫。

data 欄位是選用的，並且可以包含任意鍵值組。 未指定提供重複鍵的行為。

error 欄位是選用的，並且可以設為 true 以指出錯誤跨距。

當跨距以陣列形式給定時，該端點還會接受跨距批次：

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

對於使用「追蹤 SDK Web 服務」接收的追蹤，會套用與「Java 追蹤 SDK」相同的 轉換及服務/端點命名 規則。 特別是 data 中的這些鍵值組用於命名: service、 endpoint和 call.name。

附註: 在具有 Instana 代理程式 Helm 圖表的 Kubernetes 上提供的選用 Instana 代理程式服務 與追蹤 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