feat: Add simple API, timestampWithMs helper

Author: HazAT

packages/hub/src/hub.ts

@@ -11,7 +11,7 @@ import {
   SpanContext,
   User,
 } from '@sentry/types';
-import { consoleSandbox, dynamicRequire, getGlobalObject, logger, uuid4 } from '@sentry/utils';
+import { consoleSandbox, dynamicRequire, getGlobalObject, logger, timestampWithMs, uuid4 } from '@sentry/utils';
 
 import { Carrier, Layer } from './interfaces';
 import { Scope } from './scope';
@@ -253,7 +253,7 @@ export class Hub implements HubInterface {
       return;
     }
 
-    const timestamp = new Date().getTime() / 1000;
+    const timestamp = timestampWithMs();
     const mergedBreadcrumb = { timestamp, ...breadcrumb };
     const finalBreadcrumb = beforeBreadcrumb
       ? (consoleSandbox(() => beforeBreadcrumb(mergedBreadcrumb, hint)) as Breadcrumb | null)
@@ -389,17 +389,22 @@ export class Hub implements HubInterface {
   /**
    * @inheritDoc
    */
-  public startSpan(spanContext?: SpanContext): Span {
-    const scope = this.getScope();
+  public startSpan(spanContext?: SpanContext, bindOnScope: boolean = false): Span {
+    const top = this.getStackTop();
 
-    if (scope) {
-      const span = scope.getSpan();
+    const simpleNewSpan = new Span(spanContext);
+    if (top.scope && top.client) {
+      if (bindOnScope) {
+        top.scope.setSpan(simpleNewSpan);
+        return simpleNewSpan;
+      }
+      const span = top.scope.getSpan();
       if (span) {
         return span.newSpan(spanContext);
       }
     }
 
-    return new Span(spanContext);
+    return simpleNewSpan;
   }
 
   /**

packages/hub/src/scope.ts

@@ -1,5 +1,5 @@
 import { Breadcrumb, Event, EventHint, EventProcessor, Scope as ScopeInterface, Severity, User } from '@sentry/types';
-import { getGlobalObject, isThenable, normalize, SyncPromise } from '@sentry/utils';
+import { getGlobalObject, isThenable, normalize, SyncPromise, timestampWithMs } from '@sentry/utils';
 
 import { Span } from './span';
 
@@ -253,7 +253,7 @@ export class Scope implements ScopeInterface {
    * @inheritDoc
    */
   public addBreadcrumb(breadcrumb: Breadcrumb, maxBreadcrumbs?: number): this {
-    const timestamp = new Date().getTime() / 1000;
+    const timestamp = timestampWithMs();
     const mergedBreadcrumb = { timestamp, ...breadcrumb };
 
     this._breadcrumbs =

packages/hub/src/span.ts

@@ -1,5 +1,5 @@
 import { Span as SpanInterface, SpanContext } from '@sentry/types';
-import { uuid4 } from '@sentry/utils';
+import { timestampWithMs, uuid4 } from '@sentry/utils';
 
 export const TRACEPARENT_REGEXP = /^[ \t]*([0-9a-f]{32})?-?([0-9a-f]{16})?-?([01])?[ \t]*$/;
 
@@ -8,57 +8,57 @@ export const TRACEPARENT_REGEXP = /^[ \t]*([0-9a-f]{32})?-?([0-9a-f]{16})?-?([01
  */
 export class Span implements SpanInterface, SpanContext {
   /**
-   * Trace ID
+   * @inheritDoc
    */
   private readonly _traceId: string = uuid4();
 
   /**
-   * Span ID
+   * @inheritDoc
    */
   private readonly _spanId: string = uuid4().substring(16);
 
   /**
-   * Parent Span ID
+   * @inheritDoc
    */
   private readonly _parentSpanId?: string;
 
   /**
-   * Has the sampling decision been made?
+   * @inheritDoc
    */
   public readonly sampled?: boolean;
 
   /**
    * Timestamp when the span was created.
    */
-  public readonly startTimestamp: number = new Date().getTime() / 1000;
+  public readonly startTimestamp: number = timestampWithMs();
 
   /**
    * Finish timestamp of the span.
    */
   public timestamp?: number;
 
   /**
-   * Transaction of the Span.
+   * @inheritDoc
    */
   public transaction?: string;
 
   /**
-   * Operation of the Span.
+   * @inheritDoc
    */
   public op?: string;
 
   /**
-   * Description of the Span.
+   * @inheritDoc
    */
   public description?: string;
 
   /**
-   * Tags of the Span.
+   * @inheritDoc
    */
   public tags?: { [key: string]: string };
 
   /**
-   * Data of the Span.
+   * @inheritDoc
    */
   public data?: { [key: string]: any };
 
@@ -101,7 +101,10 @@ export class Span implements SpanInterface, SpanContext {
     }
   }
 
-  /** JSDoc */
+  /**
+   * Creates a new `Span` while setting the current `Span.id` as `parentSpanId`.
+   * Also the `sampled` decision will be inherited.
+   */
   public newSpan(spanContext?: Pick<SpanContext, Exclude<keyof SpanContext, 'spanId'>>): Span {
     const span = new Span({
       ...spanContext,
@@ -116,7 +119,7 @@ export class Span implements SpanInterface, SpanContext {
   }
 
   /**
-   * Continues a trace
+   * Continues a trace from a string (usually the header).
    * @param traceparent Traceparent string
    */
   public static fromTraceparent(
@@ -131,7 +134,6 @@ export class Span implements SpanInterface, SpanContext {
       } else if (matches[3] === '0') {
         sampled = false;
       }
-
       return new Span({
         ...spanContext,
         parentSpanId: matches[2],
@@ -146,7 +148,7 @@ export class Span implements SpanInterface, SpanContext {
    * Sets the finish timestamp on the current span
    */
   public finish(): void {
-    this.timestamp = new Date().getTime() / 1000;
+    this.timestamp = timestampWithMs();
     this.finishedSpans.push(this);
   }
 

packages/minimal/src/index.ts

@@ -1,5 +1,5 @@
 import { getCurrentHub, Hub, Scope } from '@sentry/hub';
-import { Breadcrumb, Event, Severity, User } from '@sentry/types';
+import { Breadcrumb, Event, Severity, Span, SpanContext, User } from '@sentry/types';
 
 /**
  * This calls a function on the current hub.
@@ -166,3 +166,28 @@ export function withScope(callback: (scope: Scope) => void): void {
 export function _callOnClient(method: string, ...args: any[]): void {
   callOnHub<void>('_invokeClient', method, ...args);
 }
+
+/**
+ * This functions starts a span. If just a `SpanContext` is passed and there is already a Span
+ * on the Scope, the created Span will have a reference to the one on the Scope.
+ * If a Span is on the current Scope it is considered a `transaction`.
+ * When using the second parameter it will set the created Span on the Scope (replacing whats there).
+ * This can be used as a shortcut to not set it manually on the Scope.
+ *
+ * @param spanContext Properties with which the span should be created
+ * @param bindOnScope Determines if the started span will be set on the Scope
+ */
+export function startSpan(spanContext?: SpanContext, bindOnScope?: boolean): Span {
+  return callOnHub<Span>('startSpan', spanContext, bindOnScope);
+}
+
+/**
+ * This finishes the passed `Span`. If the `Span` has the property `transaction` set and it's bound on the
+ * current Scope, an `transaction` Event will be sent to Sentry containing all finished Spans inbetween.
+ * Returns either an `event.id` or `undefined` in case event wasn't sent.
+ *
+ * @param span `Span` instance that was created by {@link startSpan}
+ */
+export function finishSpan(span: Span): string | undefined {
+  return callOnHub<string | undefined>('startSpan', span);
+}

packages/types/src/hub.ts

@@ -172,9 +172,24 @@ export interface Hub {
   /** Returns all trace headers that are currently on the top scope. */
   traceHeaders(): { [key: string]: string };
 
-  /** JSDoc */
-  startSpan(spanContext?: SpanContext): Span;
+  /**
+   * This functions starts a span. If just a `SpanContext` is passed and there is already a Span
+   * on the Scope, the created Span will have a reference to the one on the Scope.
+   * If a Span is on the current Scope it is considered a `transaction`.
+   * When using the second parameter it will set the created Span on the Scope (replacing whats there).
+   * This can be used as a shortcut to not set it manually on the Scope.
+   *
+   * @param spanContext Properties with which the span should be created
+   * @param bindOnScope Determines if the started span will be set on the Scope
+   */
+  startSpan(spanContext?: SpanContext, bindOnScope?: boolean): Span;
 
-  /** JSDoc */
+  /**
+   * This finishes the passed `Span`. If the `Span` has the property `transaction` set and it's bound on the
+   * current Scope, an `transaction` Event will be sent to Sentry containing all finished Spans inbetween.
+   * Returns either an `event.id` or `undefined` in case event wasn't sent.
+   *
+   * @param span `Span` instance that was created by {@link startSpan}
+   */
   finishSpan(span: Span): string | undefined;
 }

packages/types/src/span.ts

@@ -8,15 +8,43 @@ export interface Span {
   toJSON(): object;
 }
 
-/** JSDoc */
+/** Interface holder all properties that can be set on a Span on creation. */
 export interface SpanContext {
+  /**
+   * Description of the Span.
+   */
   description?: string;
+  /**
+   * Operation of the Span.
+   */
   op?: string;
+  /**
+   * Parent Span ID
+   */
   parentSpanId?: string;
+  /**
+   * Has the sampling decision been made?
+   */
   sampled?: boolean;
+  /**
+   * Span ID
+   */
   spanId?: string;
+  /**
+   * Trace ID
+   */
   traceId?: string;
+  /**
+   * Transaction of the Span.
+   */
   transaction?: string;
+  /**
+   * Tags of the Span.
+   */
   tags?: { [key: string]: string };
+
+  /**
+   * Data of the Span.
+   */
   data?: { [key: string]: any };
 }

packages/utils/src/misc.ts

@@ -220,3 +220,10 @@ export function addExceptionTypeValue(
   event.exception.values[0].type = event.exception.values[0].type || type || 'Error';
   event.exception.values[0].mechanism = event.exception.values[0].mechanism || mechanism;
 }
+
+/**
+ * Returns a timestamp in seconds with milliseconds precision.
+ */
+export function timestampWithMs(): number {
+  return new Date().getTime() / 1000;
+}