✨Add initial span interface

packages/opentelemetry-types/src/index.ts

@@ -13,3 +13,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+export * from './trace/span';
+export * from './trace/span_context';
+export * from './trace/span_kind';
+export * from './trace/status';
+export * from './trace/link';
+export * from './trace/attributes';
+export * from './trace/traceoptions';
+export * from './trace/tracestate';

packages/opentelemetry-types/src/trace/attributes.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+
+ /** Defines a attributes interface. */
+export interface Attributes {
+  [attributeKey: string]: unknown;
+}

packages/opentelemetry-types/src/trace/link.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 { Attributes } from './attributes';
+import { SpanContext } from './span_context';
+
+/**
+ * A pointer from the current span to another span in the same trace or in a
+ * different trace.
+ */
+export interface Link {
+  /** The SpanContext of a linked span. */
+  spanContext: SpanContext;
+  /** A set of attributes on the link. */
+  attributes: Attributes;
+}

packages/opentelemetry-types/src/trace/span.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 { SpanContext } from './span_context';
+import { Status } from './status';
+
+/**
+ * An interface that represents a span. A span represents a single operation
+ * within a trace. Examples of span might include remote procedure calls or a
+ * in-process function calls to sub-components. A Trace has a single, top-level
+ * "root" Span that in turn may have zero or more child Spans, which in turn
+ * may have children.
+ */
+export interface Span {
+  /**
+   * Returns the SpanContext object associated with this Span.
+   *
+   * @returns the SpanContext object associated with this Span.
+   */
+  context(): SpanContext;
+
+  // /**
+  //  * # TODO
+  //  * Returns the Tracer object used to create this Span.
+  //  * https://github.com/open-telemetry/opentelemetry-specification/issues/21
+  //  */
+  // tracer(): Tracer;
+
+  /**
+   * Sets an attribute to the span.
+   *
+   * @param key the key for this attribute.
+   * @param value the value for this attribute.
+   */
+  setAttribute(key: string, value: unknown): this;
+
+  /**
+   * Adds an event to the Span.
+   *
+   * @param name the name of the event.
+   * @param [attributes] the attributes that will be added; these are
+   *     associated with this event.
+   */
+  addEvent(name: string, attributes?: { [key: string]: unknown }): this;
+
+  /**
+   * Adds a link to the Span.
+   *
+   * @param spanContext the context of the linked span.
+   * @param [attributes] the attributes that will be added; these are
+   *     associated with this link.
+   */
+  addLink(spanContext: SpanContext, attributes?: { [key: string]: unknown }): this;
+
+  /**
+   * Sets a status to the span. If used, this will override the default Span
+   * status. Default is 'OK'.
+   *
+   * @param status the Status to set.
+   */
+  setStatus(status: Status): this;
+
+  /**
+   * Updates the Span name.
+   *
+   * TODO (revision): https://github.com/open-telemetry/opentelemetry-specification/issues/119
+   *
+   * @param name the Span name.
+   */
+  updateName(name: string): this;
+
+  /**
+   * Marks the end of Span execution.
+   *
+   * Call to End of a Span MUST not have any effects on child spans. Those may
+   * still be running and can be ended later.
+   *
+   * Do not return `this`. The Span generally should not be used after it
+   * is ended so chaining is not desired in this context.
+   *
+   * @param [endTime] the timestamp to set as Span's end time. If not provided,
+   *     use the current time as the span's end time.
+   */
+  end(endTime?: number): void;
+
+  /**
+   * Returns the flag whether this span will be recorded.
+   *
+   * @returns true if this Span is active and recording information like events
+   * with the AddEvent operation and attributes using setAttributes.
+   */
+  isRecordingEvents(): boolean;
+}

packages/opentelemetry-types/src/trace/span_context.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 { TraceState } from './tracestate';
+import { TraceOptions } from './traceoptions';
+
+/**
+ * A SpanContext represents the portion of a Span which must be serialized and
+ * propagated along side of a distributed context.
+ */
+export interface SpanContext {
+  /**
+   * The ID of the trace that this span belongs to. It is worldwide unique
+   * with practically sufficient probability by being made as 16 randomly
+   * generated bytes, encoded as a 32 lowercase hex characters corresponding to
+   * 128 bits.
+   */
+  traceId: string;
+  /**
+   * The ID of the Span. It is globally unique with practically sufficient
+   * probability by being made as 8 randomly generated bytes, encoded as a 16
+   * lowercase hex characters corresponding to 64 bits.
+   */
+  spanId: string;
+  /**
+   * Trace options to propagate.
+   *
+   * It is represented as 1 byte (bitmap). Bit to represent whether trace is
+   * sampled or not.
+   * SAMPLED_VALUE = 0x1 and NOT_SAMPLED_VALUE = 0x0;
+   */
+  traceOptions?: TraceOptions;
+  /**
+   * Tracing-system-specific info to propagate.
+   *
+   * The tracestate field value is a `list` as defined below. The `list` is a
+   * series of `list-members` separated by commas `,`, and a list-member is a
+   * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
+   * surrounding `list-members` are ignored. There can be a maximum of 32
+   * `list-members` in a `list`.
+   * More Info: https://www.w3.org/TR/trace-context/#tracestate-field
+   *
+   * Examples:
+   *     Single tracing system (generic format):
+   *         tracestate: rojo=00f067aa0ba902b7
+   *     Multiple tracing systems (with different formatting):
+   *         tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
+   */
+  traceState?: TraceState;
+}

packages/opentelemetry-types/src/trace/span_kind.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+
+/**
+ * Type of span. Can be used to specify additional relationships between spans
+ * in addition to a parent/child relationship.
+ */
+export enum SpanKind {
+  /** Default value. Indicates that the span is used internally. */
+  INTERNAL = 0,
+
+  /**
+   * Indicates that the span covers server-side handling of an RPC or other
+   * remote request.
+   */
+  SERVER = 1,
+
+  /**
+   * Indicates that the span covers the client-side wrapper around an RPC or
+   * other remote request.
+   */
+  CLIENT = 2,
+
+  /**
+   * Indicates that the span describes producer sending a message to a
+   * broker. Unlike client and server, there is no direct critical path latency
+   * relationship between producer and consumer spans.
+   */
+  PRODUCER = 3,
+
+  /**
+   * Indicates that the span describes consumer receiving a message from a
+   * broker. Unlike client and server, there is no direct critical path latency
+   * relationship between producer and consumer spans.
+   */
+  CONSUMER = 4,
+}