Jaeger: Document external interfaces

[jpkrohling]

• agent's HTTP/JSON API polled by the clients
• agent's UDP/Thrift APIs (we already have IDLs for that)
• collector's HTTP POST API (Thrift and JSON)

Discussion: https://groups.google.com/d/msg/jaeger-tracing/L27aTD9kXRc/-Y3PTdy-BAAJ

Related to #404 .

[pavolloffay]

Also related to https://github.com/jaegertracing/jaeger/issues/158 and #206

[jpkrohling]

Perhaps this would also fit on this task, as suggested on Gitter by @NicolasT

Are there any docs on how Jaeger clients are supposed to encode trace/span-id's etc in e.g. HTTP headers, or should one reverse-engineer one of the existing client libs?

[yurishkuro]

I hope this would be mostly automated once #773 is done

[PikBot]

@yurishkuro would it be better to wait for #773 before I start documenting the items listed by @jpkrohling ?

[yurishkuro]

Yes, I recommend waiting for #773

[jpkrohling]

@yurishkuro, do we have an idea on when #773 would be done? This is blocking the project in achieving the CII Best Practices, as we need to document the input/output of the "external" interfaces.

[facundominguez]

Hello. I'm trying to use the REST API from jaeger-query in regressions tests of a client library for jaeger.

Moreover, I expected using jaeger would give me the ability to automate analysis of the traces. Not having documentation to query the traces poses a difficulty for adoption. Is there a better way to do this?

[black-adder]

For the time being, here's the relevant query endpoints:

GET api/traces/:traceID
GET api/services
GET api/operations?service=:svc

GET api/traces

The relevant params for the api/traces endpoint is below:

query ::= param | param '&' query
param ::= service | operation | limit | start | end | minDuration | maxDuration | tag | tags
service ::= 'service=' strValue
operation ::= 'operation=' strValue
limit ::= 'limit=' intValue
start ::= 'start=' intValue in unix microseconds
end ::= 'end=' intValue in unix microseconds
minDuration ::= 'minDuration=' strValue (units are "ns", "us" (or "µs"), "ms", "s", "m", "h")
maxDuration ::= 'maxDuration=' strValue (units are "ns", "us" (or "µs"), "ms", "s", "m", "h")
tag ::= 'tag=' key | 'tag=' keyvalue
key := strValue
keyValue := strValue ':' strValue
tags :== 'tags=' jsonMap

The return format is JSON (NOTE we don't actually support pagination at the moment but it is exposed in the response):

{
    "data": SEE BELOW,
    "total": INT,
    "limit": INT,
    "offset": INT,
    "errors": [
        {
            "code": INT,
            "msg": STRING,
            "traceID": STRING
        }
    ]
}

where data can be different data types based on the request. The api/traces and api/traces/:traceID endpoints, will return an array of jaeger traces. api/services
and api/operations?service=:svc will return an array of strings.

I'll think of a better location to document this. Swagger might be a bit overkill given the timelines, I could just add this to the documentation page but I'd prefer if the documentation versioning change lands before I go ahead and do that.

[GuangmingLuo]

@black-adder Hi, as you said those query endpoints are always available from outside, right ? If this is correct, please document that either by Swagger or RAML. A lot of us are waiting for the documentation to make use of the APIs.

[fommil]

subscribers to this thread may like to know about https://github.com/symbiont-io/jaeger-flamegraph which is a little tool I wrote to consume data from this undocumented endpoint and produce a flamegraph.

It would be super useful to me if the API was adapted to

1. not have a limit by default (or -1 to disable it)
2. to download data for all services in a single JSON