Zipkin Exporter (open-telemetry#192)

* feat(zipkin-exporter): implement

* fix(zipkin): use time fns

* refactor(exporter-zipkin): linter fix

Author: Peter Marton

packages/opentelemetry-exporter-zipkin/package.json

@@ -9,6 +9,7 @@
     "tdd": "yarn test -- --watch-extensions ts --watch",
     "clean": "rimraf build/*",
     "check": "gts check",
+    "codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../",
     "compile": "tsc -p .",
     "fix": "gts fix"
   },
@@ -35,10 +36,12 @@
   },
   "devDependencies": {
     "@types/mocha": "^5.2.7",
+    "@types/nock": "^10.0.3",
     "@types/node": "^12.6.9",
     "codecov": "^3.5.0",
     "gts": "^1.1.0",
     "mocha": "^6.2.0",
+    "nock": "^10.0.6",
     "nyc": "^14.1.1",
     "tslint-microsoft-contrib": "^6.2.0",
     "tslint-consistent-codestyle":"^1.15.1",
@@ -47,5 +50,8 @@
     "typescript": "^3.5.3"
   },
   "dependencies": {
+    "@opentelemetry/core": "^0.0.1",
+    "@opentelemetry/basic-tracer": "^0.0.1",
+    "@opentelemetry/types": "^0.0.1"
   }
 }

packages/opentelemetry-exporter-zipkin/src/index.ts

@@ -13,3 +13,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+export * from './zipkin';

packages/opentelemetry-exporter-zipkin/src/transform.ts

@@ -0,0 +1,95 @@
+/*!
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as types from '@opentelemetry/types';
+import { ReadableSpan } from '@opentelemetry/basic-tracer';
+import { hrTimeToMilliseconds } from '@opentelemetry/core';
+import * as zipkinTypes from './types';
+
+const ZIPKIN_SPAN_KIND_MAPPING = {
+  [types.SpanKind.CLIENT]: zipkinTypes.SpanKind.CLIENT,
+  [types.SpanKind.SERVER]: zipkinTypes.SpanKind.SERVER,
+  [types.SpanKind.CONSUMER]: zipkinTypes.SpanKind.CONSUMER,
+  [types.SpanKind.PRODUCER]: zipkinTypes.SpanKind.PRODUCER,
+  // When absent, the span is local.
+  [types.SpanKind.INTERNAL]: undefined,
+};
+
+export const statusCodeTagName = 'ot.status_code';
+export const statusDescriptionTagName = 'ot.status_description';
+
+/**
+ * Translate OpenTelemetry ReadableSpan to ZipkinSpan format
+ * @param span Span to be translated
+ */
+export function toZipkinSpan(
+  span: ReadableSpan,
+  serviceName: string,
+  statusCodeTagName: string,
+  statusDescriptionTagName: string
+): zipkinTypes.Span {
+  const zipkinSpan: zipkinTypes.Span = {
+    traceId: span.spanContext.traceId,
+    parentId: span.parentSpanId,
+    name: span.name,
+    id: span.spanContext.spanId,
+    kind: ZIPKIN_SPAN_KIND_MAPPING[span.kind],
+    timestamp: hrTimeToMilliseconds(span.startTime),
+    duration: hrTimeToMilliseconds(span.duration),
+    localEndpoint: { serviceName },
+    tags: _toZipkinTags(
+      span.attributes,
+      span.status,
+      statusCodeTagName,
+      statusDescriptionTagName
+    ),
+    annotations: span.events.length
+      ? _toZipkinAnnotations(span.events)
+      : undefined,
+  };
+
+  return zipkinSpan;
+}
+
+/** Converts OpenTelemetry Attributes and Status to Zipkin Tags format. */
+export function _toZipkinTags(
+  attributes: types.Attributes,
+  status: types.Status,
+  statusCodeTagName: string,
+  statusDescriptionTagName: string
+): zipkinTypes.Tags {
+  const tags: { [key: string]: string } = {};
+  for (const key of Object.keys(attributes)) {
+    tags[key] = String(attributes[key]);
+  }
+  tags[statusCodeTagName] = String(types.CanonicalCode[status.code]);
+  if (status.message) {
+    tags[statusDescriptionTagName] = status.message;
+  }
+  return tags;
+}
+
+/**
+ * Converts OpenTelemetry Events to Zipkin Annotations format.
+ */
+export function _toZipkinAnnotations(
+  events: types.TimedEvent[]
+): zipkinTypes.Annotation[] {
+  return events.map(event => ({
+    timestamp: hrTimeToMilliseconds(event.time),
+    value: event.name,
+  }));
+}

packages/opentelemetry-exporter-zipkin/src/types.ts

@@ -0,0 +1,180 @@
+/*!
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as types from '@opentelemetry/types';
+
+/**
+ * Exporter config
+ */
+export interface ExporterConfig {
+  logger?: types.Logger;
+  serviceName: string;
+  url?: string;
+  // Initiates a request with spans in memory to the backend.
+  forceFlush?: boolean;
+  // Optional mapping overrides for OpenTelemetry status code and description.
+  statusCodeTagName?: string;
+  statusDescriptionTagName?: string;
+}
+
+/**
+ * Zipkin Span
+ * @see https://github.com/openzipkin/zipkin-api/blob/master/zipkin2-api.yaml
+ */
+export interface Span {
+  /**
+   * Trace identifier, set on all spans within it.
+   */
+  traceId: string;
+  /**
+   * The logical operation this span represents in lowercase (e.g. rpc method).
+   * Leave absent if unknown.
+   */
+  name: string;
+  /**
+   * The parent span ID or absent if this the root span in a trace.
+   */
+  parentId?: string;
+  /**
+   * Unique 64bit identifier for this operation within the trace.
+   */
+  id: string;
+  /**
+   * When present, kind clarifies timestamp, duration and remoteEndpoint.
+   * When absent, the span is local or incomplete.
+   */
+  kind?: SpanKind;
+  /**
+   * Epoch microseconds of the start of this span, possibly absent if
+   * incomplete.
+   */
+  timestamp: number;
+  /**
+   * Duration in microseconds of the critical path, if known.
+   */
+  duration: number;
+  /**
+   * True is a request to store this span even if it overrides sampling policy.
+   * This is true when the `X-B3-Flags` header has a value of 1.
+   */
+  debug?: boolean;
+  /**
+   * True if we are contributing to a span started by another tracer (ex on a
+   * different host).
+   */
+  shared?: boolean;
+  /**
+   * The host that recorded this span, primarily for query by service name.
+   */
+  localEndpoint: Endpoint;
+  /**
+   * Associates events that explain latency with the time they happened.
+   */
+  annotations?: Annotation[];
+  /**
+   * Tags give your span context for search, viewing and analysis.
+   */
+  tags: Tags;
+  /**
+   * TODO: `remoteEndpoint`, do we need to support it?
+   * When an RPC (or messaging) span, indicates the other side of the
+   * connection.
+   */
+}
+
+/**
+ * Associates an event that explains latency with a timestamp.
+ * Unlike log statements, annotations are often codes. Ex. "ws" for WireSend
+ * Zipkin v1 core annotations such as "cs" and "sr" have been replaced with
+ * Span.Kind, which interprets timestamp and duration.
+ */
+export interface Annotation {
+  /**
+   * Epoch microseconds of this event.
+   * For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC
+   */
+  timestamp: number;
+  /**
+   * Usually a short tag indicating an event, like "error"
+   * While possible to add larger data, such as garbage collection details, low
+   * cardinality event names both keep the size of spans down and also are easy
+   * to search against.
+   */
+  value: string;
+}
+
+/**
+ * The network context of a node in the service graph.
+ */
+export interface Endpoint {
+  /**
+   * Lower-case label of this node in the service graph, such as "favstar".
+   * Leave absent if unknown.
+   * This is a primary label for trace lookup and aggregation, so it should be
+   * intuitive and consistent. Many use a name from service discovery.
+   */
+  serviceName?: string;
+  /**
+   * The text representation of the primary IPv4 address associated with this
+   * connection. Ex. 192.168.99.100 Absent if unknown.
+   */
+  ipv4?: string;
+  /**
+   * The text representation of the primary IPv6 address associated with a
+   * connection. Ex. 2001:db8::c001 Absent if unknown.
+   * Prefer using the ipv4 field for mapped addresses.
+   */
+  port?: number;
+}
+
+/**
+ * Adds context to a span, for search, viewing and analysis.
+ * For example, a key "your_app.version" would let you lookup traces by version.
+ * A tag "sql.query" isn't searchable, but it can help in debugging when viewing
+ * a trace.
+ */
+export interface Tags {
+  [tagKey: string]: unknown;
+}
+
+/**
+ * When present, kind clarifies timestamp, duration and remoteEndpoint. When
+ * absent, the span is local or incomplete. Unlike client and server, there
+ * is no direct critical path latency relationship between producer and
+ * consumer spans.
+ * `CLIENT`
+ *   timestamp is the moment a request was sent to the server.
+ *   duration is the delay until a response or an error was received.
+ *   remoteEndpoint is the server.
+ * `SERVER`
+ *   timestamp is the moment a client request was received.
+ *   duration is the delay until a response was sent or an error.
+ *   remoteEndpoint is the client.
+ * `PRODUCER`
+ *   timestamp is the moment a message was sent to a destination.
+ *   duration is the delay sending the message, such as batching.
+ *   remoteEndpoint is the broker.
+ * `CONSUMER`
+ *   timestamp is the moment a message was received from an origin.
+ *   duration is the delay consuming the message, such as from backlog.
+ *   remoteEndpoint - Represents the broker. Leave serviceName absent if unknown.
+ */
+export enum SpanKind {
+  CLIENT = 'CLIENT',
+  SERVER = 'SERVER',
+  CONSUMER = 'CONSUMER',
+  PRODUCER = 'PRODUCER',
+}