Feat(V3): Support for experimental metrics

CHANGELOG.md

@@ -53,6 +53,7 @@ Sentry.init({
 
 ### Features
 
+- Add experimental Metric support for Web and iOS ([#1055](https://github.com/getsentry/sentry-capacitor/pull/1055))
 - Add Fallback to JavaScript SDK when Native SDK fails to initialize ([#1043](https://github.com/getsentry/sentry-capacitor/pull/1043))
 - Add spotlight integration `spotlightIntegration`. ([#1039](https://github.com/getsentry/sentry-capacitor/pull/1039))
 

example/ionic-angular-v6/src/app/tab1/tab1.page.html

@@ -72,5 +72,9 @@
       Clear Test Context
       <ion-button (click)="clearTestContext()">Clear Test Context</ion-button>
     </label>
+    <label>
+      Create Metric
+      <ion-button (click)="createMetric()">Create Metric</ion-button>
+    </label>
   </section>
 </ion-content>

example/ionic-angular-v6/src/app/tab1/tab1.page.ts

@@ -138,4 +138,11 @@ export class Tab1Page {
   public clearTestContext(): void {
     Sentry.setContext('TEST-CONTEXT', null);
   }
+
+  public createMetric(): void {
+    // Create a metric using Sentry metrics API
+    Sentry.metrics.count('test.metric.counter', 1,
+      { attributes: { from_test_app: true } },
+    );
+    }
 }

example/ionic-angular-v7/src/app/app.module.ts

@@ -23,6 +23,12 @@ Sentry.init(
     // Whether SDK should be enabled or not
     enabled: true,
     // Use the tracing integration to see traces and add performance monitoring
+    _experiments: {
+      enableMetrics: true,
+    },
+    beforeSendMetric: (metric) => {
+      return metric;
+    },
     integrations: [
       Sentry.browserTracingIntegration(),
       Sentry.replayIntegration({

example/ionic-angular-v7/src/app/tab1/tab1.page.html

@@ -72,5 +72,9 @@
       Clear Test Context
       <ion-button (click)="clearTestContext()">Clear Test Context</ion-button>
     </label>
+    <label>
+      Create Metric
+      <ion-button (click)="createMetric()">Create Metric</ion-button>
+    </label>
   </section>
 </ion-content>

example/ionic-angular-v7/src/app/tab1/tab1.page.ts

@@ -138,4 +138,11 @@ export class Tab1Page {
   public clearTestContext(): void {
     Sentry.setContext('TEST-CONTEXT', null);
   }
+
+  public createMetric(): void {
+    // Create a metric using Sentry metrics API
+    Sentry.metrics.count('test.metric.counter', 1,
+      { attributes: { from_test_app: true } },
+    );
+  }
 }

example/ionic-vue3/src/views/HomePage.vue

@@ -1,43 +1,64 @@
 <!-- SentryCapacitorVue.vue -->
 <script lang="ts">
-import { IonButton, IonContent, IonFooter, IonHeader, IonTitle, IonToolbar, IonPage  } from '@ionic/vue';
+import {
+  IonButton,
+  IonContent,
+  IonFooter,
+  IonHeader,
+  IonTitle,
+  IonToolbar,
+  IonPage,
+} from '@ionic/vue';
 
-import * as Sentry from "@sentry/capacitor"
+import * as Sentry from '@sentry/capacitor';
 
-  export default {
+export default {
   name: 'HomePageView',
-  components: { IonButton, IonContent, IonFooter, IonHeader, IonTitle, IonToolbar, IonPage },
+  components: {
+    IonButton,
+    IonContent,
+    IonFooter,
+    IonHeader,
+    IonTitle,
+    IonToolbar,
+    IonPage,
+  },
   methods: {
     createMessage() {
       Sentry.captureMessage('Hello VUE');
     },
     handledError() {
       try {
-        throw Error("A handled error");
+        throw Error('A handled error');
       } catch (ex) {
         Sentry.captureException(ex);
       }
     },
     crash() {
       Sentry.nativeCrash();
-    }
-  }
+    },
+    createMetric() {
+      // Create a metric using Sentry metrics API
+      Sentry.metrics.count('test.metric.counter', 1, {
+        attributes: { from_test_app: true },
+      });
+    },
+  },
 };
-
-
 </script>
 
 <template>
   <ion-page>
-  <ion-header :translucent="true">
-    <ion-toolbar>
-      <ion-title>Sentry Capacitor Vue</ion-title>
-    </ion-toolbar>
-  </ion-header>
-  <ion-content :fullscreen="true" class="ion-padding">
-      <ion-button  @click="createMessage">Create Message</ion-button>
-      <ion-button  @click="handledError">Handled Error</ion-button>
-      <ion-button  @click="crash">Crash</ion-button>
-  </ion-content>
+    <ion-header :translucent="true">
+      <ion-toolbar>
+        <ion-title>Sentry Capacitor Vue</ion-title>
+      </ion-toolbar>
+    </ion-header>
+    <ion-content :fullscreen="true" class="ion-padding">
+      <ion-button @click="createMessage">Create Message</ion-button>
+      <ion-button @click="handledError">Handled Error</ion-button>
+      <ion-button @click="crash">Crash</ion-button>
+      <ion-button @click="createMetric">Create Metric</ion-button>
+    </ion-content>
   </ion-page>
 </template>

src/index.ts

@@ -12,6 +12,7 @@ export type {
   Stacktrace,
   Thread,
   User,
+  Metric
 } from '@sentry/core';
 
 export type { Scope } from '@sentry/core';
@@ -49,7 +50,7 @@ export {
   startIdleSpan,
 } from '@sentry/core';
 
-export { replayIntegration, browserTracingIntegration, registerSpanErrorInstrumentation, logger } from '@sentry/browser';
+export { metrics, replayIntegration, browserTracingIntegration, registerSpanErrorInstrumentation, logger } from '@sentry/browser';
 
 export { pauseAppHangTracking, resumeAppHangTracking } from './wrapper';
 

src/options.ts

@@ -1,5 +1,5 @@
 import type { BrowserOptions, makeFetchTransport } from '@sentry/browser';
-import type { ClientOptions } from '@sentry/core';
+import type { ClientOptions, Metric } from '@sentry/core';
 import type { NuxtOptions, VueOptions } from './siblingOptions';
 
 // Direct reference of BrowserTransportOptions is not compatible with strict builds of latest versions of Typescript 5.
@@ -95,19 +95,50 @@ export interface BaseCapacitorOptions {
      */
     nuxtClientOptions?: NuxtOptions;
   };
+
+    /**
+   * Options which are in beta, or otherwise not guaranteed to be stable.
+   */
+    _experiments?: {
+
+      /**
+       * If metrics support should be enabled.
+       *
+       * @default false
+       * @experimental
+       * @platforms web and iOS only. On the future it will be enabled on Android.
+       */
+      enableMetrics?: boolean;
+
+      /**
+       * An event-processing callback for metrics, guaranteed to be invoked after all other metric
+       * processors. This allows a metric to be modified or dropped before it's sent.
+       *
+       * Note that you must return a valid metric from this callback. If you do not wish to modify the metric, simply return
+       * it at the end. Returning `null` will cause the metric to be dropped.
+       *
+       * @default undefined
+       * @experimental
+       * @platforms web and iOS only. On the future it will be enabled on Android.
+       *
+       * @param metric The metric generated by the SDK.
+       * @returns A new metric that will be sent | null.
+       */
+      beforeSendMetric?: (metric: Metric) => Metric | null;
+    };
 }
 
 /**
  * Configuration options for the Sentry Capacitor SDK.
  */
 export interface CapacitorOptions
-  extends Omit<BrowserOptions, '_experiments'>,
+  extends Omit<BrowserOptions, '_experiments' | 'enableMetrics'>,
   BaseCapacitorOptions { }
 
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface CapacitorTransportOptions extends BrowserTransportOptions { }
 
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface CapacitorClientOptions
-  extends ClientOptions<CapacitorTransportOptions>,
+  extends Omit<ClientOptions<CapacitorTransportOptions>, '_experiments' | 'enableMetrics'>,
   BaseCapacitorOptions { }

src/sdk.ts

@@ -80,6 +80,8 @@ finalOptions.transport = passedOptions.transport || makeNativeTransport;
     ...finalOptions,
     autoSessionTracking:
       NATIVE.platform === 'web' && finalOptions.enableAutoSessionTracking,
+    enableMetrics: finalOptions._experiments?.enableMetrics,
+    beforeSendMetric: finalOptions._experiments?.beforeSendMetric,
   } as BrowserOptions;
 
   const mobileOptions = {

src/wrapper.ts

@@ -59,7 +59,7 @@ export const NATIVE = {
             : 'application/octet-stream';
         bytesPayload = [...itemPayload];
       } else {
-        bytesContentType = 'application/vnd.sentry.items.log+json';
+        bytesContentType =  typeof itemHeader.content_type === 'string' ? itemHeader.content_type : 'application/json';
         bytesPayload = utf8ToBytes(JSON.stringify(itemPayload));
       }
 

test/helper/envelopeHelper.ts

@@ -0,0 +1,122 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+import type { DsnComponents, LogEnvelope, MetricEnvelope, SdkMetadata, SerializedLog, SerializedMetric } from '@sentry/core';
+import { createEnvelope, dsnToString } from '@sentry/core';
+import type { LogContainerItem, MetricContainerItem } from '@sentry/core/build/types/types-hoist/envelope';
+
+
+/**
+ * Based on packages/core/src/metrics/envelope.ts
+ * Creates a metric container envelope item for a list of metrics.
+ *
+ * @param items - The metrics to include in the envelope.
+ * @returns The created metric container envelope item.
+ */
+export function createMetricContainerEnvelopeItem(items: Array<SerializedMetric>): MetricContainerItem {
+  return [
+    {
+      type: 'trace_metric',
+      item_count: items.length,
+      content_type: 'application/vnd.sentry.items.trace-metric+json',
+    } as MetricContainerItem[0],
+    {
+      items,
+    },
+  ];
+}
+
+
+/**
+ * Based on getsentry/sentry-javascript/packages/core/src/logs/envelope.ts
+ * Creates a log container envelope item for a list of logs.
+ *
+ * @param items - The logs to include in the envelope.
+ * @returns The created log container envelope item.
+ */
+export function createLogContainerEnvelopeItem(items: Array<SerializedLog>): LogContainerItem {
+  return [
+    {
+      type: 'log',
+      item_count: items.length,
+      content_type: 'application/vnd.sentry.items.log+json',
+    },
+    {
+      items,
+    },
+  ];
+}
+
+/**
+ * Based on getsentry/sentry-javascript/packages/core/src/logs/envelope.ts
+ * Creates an envelope for a list of logs.
+ *
+ * Logs from multiple traces can be included in the same envelope.
+ *
+ * @param logs - The logs to include in the envelope.
+ * @param metadata - The metadata to include in the envelope.
+ * @param tunnel - The tunnel to include in the envelope.
+ * @param dsn - The DSN to include in the envelope.
+ * @returns The created envelope.
+ */
+export function createLogEnvelopeHelper(logs: Array<SerializedLog>,
+  metadata?: SdkMetadata,
+  tunnel?: string,
+  dsn?: DsnComponents,
+): LogEnvelope {
+  const headers: LogEnvelope[0] = {};
+
+  if (metadata?.sdk) {
+    headers.sdk = {
+      name: metadata.sdk.name,
+      version: metadata.sdk.version,
+    };
+  }
+
+  if (!!tunnel && !!dsn) {
+    headers.dsn = dsnToString(dsn);
+  }
+
+  return createEnvelope<LogEnvelope>(headers, [createLogContainerEnvelopeItem(logs)]);
+}
+
+/**
+ * Based on packages/core/src/metrics/envelope.ts
+ * Creates an envelope for a list of metrics.
+ *
+ * Metrics from multiple traces can be included in the same envelope.
+ *
+ * @param metrics - The metrics to include in the envelope.
+ * @param metadata - The metadata to include in the envelope.
+ * @param tunnel - The tunnel to include in the envelope.
+ * @param dsn - The DSN to include in the envelope.
+ * @returns The created envelope.
+ */
+export function createMetricEnvelopeHelper(metrics: Array<SerializedMetric>,
+  metadata?: SdkMetadata,
+  tunnel?: string,
+  dsn?: DsnComponents): MetricEnvelope {
+    const headers: MetricEnvelope[0] = {};
+
+    if (metadata?.sdk) {
+      headers.sdk = {
+        name: metadata.sdk.name,
+        version: metadata.sdk.version,
+      };
+    }
+
+    if (!!tunnel && !!dsn) {
+      headers.dsn = dsnToString(dsn);
+    }
+
+    return createEnvelope<MetricEnvelope>(headers, [createMetricContainerEnvelopeItem(metrics)]);
+}
+
+
+export function base64EnvelopeToString(envelope: string): string | undefined {
+  if (!envelope) {
+    return undefined;
+  }
+
+  const decoded = Buffer.from(envelope, 'base64').toString('utf-8');
+  return decoded;
+}
+