skywalking-java/docs/en/protocols/HTTP-API-Protocol.md

HTTP API Protocol

HTTP API Protocol defines the API data format, including api request and response data format.

Do register

Detail information about data format can be found in Register service. And register steps followings SkyWalking Trace Data Protocol v2.

• Service Register

POST http://localhost:12800/v2/service/register

Input:

{
  "services": [
    {
      "type": "normal",
      "serviceName": "Service Name"
    }
  ]
}

Output JSON Array:

[
    {
        "key": "Service Name",
        "value": 2
    }
]

• Service instance Register

POST http://localhost:12800/v2/instance/register

Input:

{
  "instances": [
    {
      "time": 1582428603392,
      "instanceUUID": "NAME:Service Instance Name",
      "properties": [
        {
          "key": "language",
          "value": "Lua"
        }
      ],
      "serviceId": 2
    }
  ]
}

OutPut:

[
    {
        "key": "NAME:Service Instance Name",
        "value": 0
    }
]

• Service instance heartbeat

POST http://localhost:12800/v2/instance/heartbeat

Input:

{
  "serviceInstanceId":20,
  "time": 1582428603392,
  "serviceInstanceUUID":"NAME:Service Instance Name"
}

OutPut:

{}

If your instance does not exist, you need to clean your local service instance metadata in your application and re-do register:

{
    "commands": [
        {
            "command": "ServiceMetadataReset",
            "args": [
                {
                    "key": "SerialNumber",
                    "value": "44bd2664-03c7-46bc-8652-52fcde0e7699"
                }
            ]
        }
    ]
}

Trace Report

POST http://localhost:12800/v2/segments

Input:

{
  "spans": [
    {
      "operationName": "/tier2/lb",
      "startTime": 1582461179910,
      "tags": [],
      "endTime": 1582461179922,
      "spanType": "Exit",
      "logs":[],
      "spanId": 1,
      "isError": false,
      "parentSpanId": 0,
      "componentId": 6000,
      "peer": "User Service Name-nginx:upstream_ip:port",
      "spanLayer": "HTTP"
    },
    {
      "operationName": "/tier2/lb",
      "startTime": 1582461179910,
      "tags": [
        {
          "key": "http.method",
          "value": "GET"
        },
        {
          "key": "http.params",
          "value": "http://127.0.0.1/tier2/lb"
        }
      ],
      "endTime": 1582461179922,
      "spanType": "Entry",
      "logs": [],
      "spanId": 0,
      "isError": false,
      "parentSpanId": -1,
      "componentId": 6000,
      "refs": [
        {
          "parentTraceSegmentId": {
            "idParts": [
              1582461179038,
              794206293,
              69887
            ]
          },
          "parentEndpointId": 0,
          "entryEndpointId": 0,
          "parentServiceInstanceId": 1,
          "parentEndpoint": "/ingress",
          "networkAddress": "#User Service Name-nginx:upstream_ip:port",
          "parentSpanId": 1,
          "entryServiceInstanceId": 1,
          "networkAddressId": 0,
          "entryEndpoint": "/ingress"
        }
      ],
      "spanLayer": "HTTP"
    }
  ],
  "serviceInstanceId": 1,
  "serviceId": 1,
  "traceSegmentId": {
    "idParts": [
      1582461179044,
      794206293,
      69887
    ]
  },
  "globalTraceIds": [
    {
      "idParts": [
        1582461179038,
        794206293,
        69887
      ]
    }
  ]
}

OutPut: