openzipkin/zipkin-api

Zipkin's language independent model and HTTP Api Definitions

zipkin-api's Issues

broke

@zhouyaohua noticed after the ASF move the zipkin uri is busted https://zipkin.io/zipkin-api/#/default/get_services

I assume this is related to the move, but we also merged a change recently to the swagger

Problem rendering Span.Kind enum markdown in swagger

Just switched GH pages and looks like span.kind isn't showing correctly.

http://zipkin.io/zipkin-api/#/paths/%252Fspans

@mohsen1 any ideas?

Clarify what fields in models are required.

Consider providing .proto for all API specs

Currently, zipkin APIs are represented as:

1. v1, http-json, through https://github.com/openzipkin/zipkin-api/blob/master/zipkin-api.yaml
2. v2, http-json, through https://github.com/openzipkin/zipkin-api/blob/master/zipkin2-api.yaml and also we have http-proto with messages defined in https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto

To make it seamless and take advantage of protobuf tooling when making zipkin clients, I think it is a good idea to have .proto for all available API specs (including v1 and v2 http json). E.g. in Envoy we can purely use protobuf helps without a detour on using json lib like rapidjson.

We can consider bringing: https://github.com/nytimes/openapi2proto to generate .proto from openapi spec.

build is toast

bintray repo no longer exists https://bintray.com/openzipkin/maven/zipkin-api
we can use the same workaround as we did in zipkin-aws in the mean time openzipkin/zipkin-aws#137

formatting issue in swagger doc

Hi, I think there might be a small formatting error in you swagger docs-

For the parameter lookback, I think the expression is supposed to be surrounded with ticks, as in line 180. The way this line is now is somewhat difficult to understand in the get traces docs.

Thanks!

Add Proto3 service definition

Now that we have a proto3 definition for Spans, we should define a service definition for them so that a GRPC server instance could be created. To start, the service definition could just be limited to the equivalent of the /spans endpoint in the current Open API spec.

make jenkins run same tests travis does

currently jenkins does nothing useful on pull requests, even if it is useful to publish a snapshot on master builds. we can either disable pull requests on jenkins, or make it run npm test.

Unclear documentation for min, maxDuration for traces

A trace is a collection of multiple spans. What does it mean to pass maxDuration or minDuration to the /api/traces endpoint? The documentation says:

minDuration: Ex. 100000 (for 100ms). Only return traces whose Span.duration is greater than or equal to minDuration microseconds.

maxDuration: Only return traces whose Span.duration is less than or equal to maxDuration microseconds. Only valid with minDuration.

Must all spans in a trace be larger than minDuration, if set? Must only one span in a trace fit within the min and max duration parameters? It's not really obvious what the intention is here.

Move repository to https://github.com/apache/incubator-zipkin-api

As part of the move to the Apache Software Foundation this repository will transfer ownership to apache and name to incubator-zipkin-api.

See https://issues.apache.org/jira/browse/INFRA-16989

swagger is crap about anchor links

I wonder if upgrading would help? It is strange to me that we cannot link to a specific part of the swagger by clicking on the heading. We frequently need to refer to sections of the doc and currently anchoring to a line in the source is easier.

Ex. clicking on span I'd expect this to change the window location url

cc @openzipkin/devops-tooling

Fix example json

from @jsw on openzipkin/zipkin-gcp#73

The JSON generated by swagger has invalid ids. Took me a while to catch that and sort it out. https://zipkin.io/zipkin-api/#/default/post_spans

Swagger link is broken

The link http://zipkin.io/zipkin-api/#/ isn't valid anymore but gets redirected to https://zipkin.apache.org/#/.

Clarify the README that this is an IDL project and no binaries are distributed

In the last release vote, it seemed evident the README could be clarified in a couple ways.

• beyond examples, further clarify that proto and swagger in this project are inputs to other tools
  • ex. point to the main docs of the IDL compiler
  • note that most users will not use these directly as tracing libraries will
• address a frequently asked question which is "why is there a maven build?"
  • this is for java projects convenience to depend on the protos.
  • this is not a binary
  • this is an alternative to the source distribution, that only includes the proto file

BinaryAnnotation type is broken

BinaryAnnotation value can be anyOf number boolean string (in other words "no" array object or list).
Besides string, we only support boolean, for the client and server address annotations. That said, some have accidentally put numeric types in their data before.

It appears this can be solved with "anyOf" or "not" in json schema 3, which is supported in OpenApi v3 (we are on v2). https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md

Unfortunately, this is in preview stage. Until this change is in (and tools support openapi 3), I think people looking for an api client will need to make one manually with an http client and a codec from one of the tracers like go or ruby similar to how we do in java

cc @devinsba @kellabyte

Add unit test to show that the swagger generated POST request is actually valid

In #51, we learned there are some subtleties about how openapi/swagger generates requests. These may be generator specific, but it could help to have something in a test that shows the POST request actually implies a ListOfSpans payload as opposed to a "spans" -> ListOfSpans. This can be more helpful as we consider moving forward with swagger versions.

cc @drolando in case you know the swag(ger)

proto3 is not documented for /api/v2/spans in the openapi/swagger doc

It should be! "application/x-protobuf" accepts a ListOfSpans from https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto#L211

We didn't say this anywhere yet

xss at https://zipkin.io/zipkin-api/

Describe the Bug

There is runing old Swagger-UI exposed at https://zipkin.io/zipkin-api/. Its possible to execute js.

Steps to Reproduce

POC alert box:

1. Go to: https://zipkin.io/zipkin-api/?configUrl=data:text/html;base64,ewoidXJsIjoiaHR0cHM6Ly9leHViZXJhbnQtaWNlLnN1cmdlLnNoL3Rlc3QueWFtbCIKfQ==

proto3 encoding

through various issues, seems proto3 is the preferred binary format for the span v2 model. We have some decisions to make, mostly around parity with ids and ips.

For example, we can choose to encode the hex ids as raw bytes (half the size of them)
We can also choose to encode IP addresses literals as raw bytes (sliding scale for ipv6; always smaller for ipv4)

Main thing is that if we do choose a binary encoding for proto3 ids and ips, there's a chance users will encode IDs incorrectly (ex encode IDs as uppercase hex, or '0x' prefixed or worse base64). There's a chance folks will handle ip raw bytes inconsistently (ex we consistently marshal ipv6 format so exact match always works).

thoughts? @openzipkin/core

Host /api/v2/spans, too

We need to document the zipkin2 span format, at first in support of POST /api/v2/spans

@mohsen1 or @openzipkin/devops-tooling .. any hands available to carve a way for the website to still work and give a choice about v1 or v2?

openzipkin/zipkin#1499

Merge master to gh-pages in TravisCI on build success

Right now, we have to manually merge changes in master to gh-pages branch to keep it updated with master. TravisCI has this feature to do stuff on build success. I've never done it before but it should be possible.

Feature request- API to get all services links by using a traceId

Hello,

Today, I could use the dependencies api to get the services link by inputting a timestamp value but it is very tedious to get the exact timestamp. We want to use the trace data to derive service links for a particular traceId. This will be of more value as we will be tagging custom attribute to the trace data like business identifiers like customerId and then using this customerId to get the traceId and then get the links of all services involved in the transaction.

Is there any appetite to add this feature to get service links based on a traceid pls? Or if someone can guide me how to do it easily or if someone already did it before?

This will come specially handy in building lineage of data in the database for a business transactions. for example - I can decide to drop all data for prospect customers after 6 months from database if their status is "LOST Opportunity". But in a big system, one may not know which all services are involved and how to clear data from 10-15 databases. Hope this makes sense on why I need such a capability. Thanks!!

Figure out why parameter descriptions aren't rendering

parameters like serviceName have a description, but the output doesn't show them

ex. http://zipkin.io/zipkin-api/#/paths/%252Ftraces doesn't render the description for serviceName

Error in response definition for Trace by Trace ID

I'm trying to use a code generator around this swagger definition, unfortunately the definition for the Trace by Trace ID endpoint is defined incorrectly, its subtle though.

    get:
      responses:
        200:
          description: OK
          schema:
            description: An array of spans that share the same trace id
            type: array
            items:
              $ref: "#/definitions/Trace"

A Trace is defined as an array of Spans already. I believe the type on this should be "#/definitions/Trace" instead of array. At least that would match what I am getting back from zipkin-query api.

[
    {
        "traceId": "fc12844aa4e770a8",
        "name": "http://example.com",
        "id": "fc12844aa4e770a8",
        "timestamp": 1460731584302000,
        "duration": 23000,
        "annotations": [
            {
                "timestamp": 1460731584302000,
                "value": "cs",
                "endpoint": {
                    "serviceName": "some-service",
                    "ipv4": "10.14.8.219",
                    "port": 7070
                }
            },
            {
                "timestamp": 1460731584325000,
                "value": "cr",
                "endpoint": {
                    "serviceName": "some-service",
                    "ipv4": "10.14.8.219",
                    "port": 7070
                }
            }
        ],
        "binaryAnnotations": [
            {
                "key": "http.uri",
                "value": "http://example.vom",
                "endpoint": {
                }
            }
        ]
    }
]

I'm in a bunch of meetings today but I will submit a PR if I get a few minutes to apply my change and test it.

missing swagger/openapi endpoint definitions for autocomplete tags

whoops reported by @ndrwrbgs who is experimenting

consider swagger 3 upgrade

From #46

The spans POST documentation is still a bit misleading. With the parameter named "spans", it seems to imply that it's expecting

{
    "spans": [{<...span...>}, {<....span...>}]
}

but it actually wants:

[{<...span...>}, {<...span...>}]

I couldn't figure out a way to acurately represent this in Swagger 2. It might be possible using Swagger 3 request body descriptions.

Publish a jar for zipkin-api to maven

The old thrift spec used to be published on zipkin here. Would it be possible to publish this as well? We use it to compile it and generate the java code.

decide if we want to validate thrift on pull request or not

Unlike swagger and proto, there's no pure javascript tool to validate or use thrifts. You have to rely on a OS binary to first generate the code. This means our travis config either has to invoke two tools or we have a binary dependency in our validate.test.js only for thrift.

another option is to simply not bother with thrift checking as we don't add anything to it anymore.

cc @apache/zipkin-committers

ParentId missing from Span definition

Swagger span definition is missing parentId

parse thrift into markdown or something

our most authoritative description of fields and nuance is the thrift. Is there some way we can parse it into markdown or something so that there's a human readable copy on zipkin.io?

ex.
https://github.com/openzipkin/zipkin-api/blob/master/thrift/zipkinCore.thrift#L272

cc @abesto @basvanbeek

Use Swagger Docs to render the API UI in gh-pages branch

int64 format not specified in some (at least one?) location

https://github.com/openzipkin/zipkin-api/blob/master/zipkin2-api.yaml line 319 has type: integer, but format: int64 is not specified. due to this, my client generator (nswag) made the Annotation.timestamp property an int32 which of course blows up. Is this yml file the source of truth or is something generating it? If the yaml file can just be edited i can go through it and see if there is this problem anywhere else and make a PR.

Thanks.

Can you provide a proto2 file or a script that generates proto2?

The reason is that the version of protobuf I use is 2.6.1 and does not support the map type. I hope to provide proto2 compatible files.

Adds avro schema for Zipkin V2 model

Currently we provide JSON and proto schemas for Zipkin V2 model but as Kafka ecosystem is becoming more integrated with Zipkin it would be good to have an avro schema.

Related to openzipkin-contrib/zipkin-storage-kafka#74 (comment)

cc @adriancole @jeqo @kotharironak