Support automatic collection of NextJS route errors

common/api-review/telemetry.api.md

@@ -4,18 +4,43 @@
 
 ```ts
 
+import { AnyValueMap } from '@opentelemetry/api-logs';
 import { FirebaseApp } from '@firebase/app';
 import { LoggerProvider } from '@opentelemetry/sdk-logs';
 
 // @public
-export function captureError(telemetry: Telemetry, error: unknown): void;
+export function captureError(telemetry: Telemetry, error: unknown, attributes?: AnyValueMap): void;
 
 // @public
 export function flush(telemetry: Telemetry): Promise<void>;
 
 // @public
 export function getTelemetry(app?: FirebaseApp): Telemetry;
 
+// @public (undocumented)
+export type InstrumentationOnRequestError = (error: unknown, errorRequest: Readonly<{
+    path: string;
+    method: string;
+    headers: NodeJS.Dict<string | string[]>;
+}>, errorContext: Readonly<RequestErrorContext>) => void | Promise<void>;
+
+// @public
+export const nextOnRequestError: InstrumentationOnRequestError;
+
+// @public
+export interface RequestErrorContext {
+    // (undocumented)
+    renderSource?: 'react-server-components' | 'react-server-components-payload' | 'server-rendering';
+    // (undocumented)
+    revalidateReason: 'on-demand' | 'stale' | undefined;
+    // (undocumented)
+    routePath: string;
+    // (undocumented)
+    routerKind: 'Pages Router' | 'App Router';
+    // (undocumented)
+    routeType: 'render' | 'route' | 'action' | 'middleware';
+}
+
 // @public
 export interface Telemetry {
     app: FirebaseApp;

docs-devsite/_toc.yaml

@@ -675,5 +675,7 @@ toc:
 - title: telemetry
   path: /docs/reference/js/telemetry.md
   section:
+  - title: RequestErrorContext
+    path: /docs/reference/js/telemetry.requesterrorcontext.md
   - title: Telemetry
     path: /docs/reference/js/telemetry.telemetry.md

docs-devsite/telemetry.md

@@ -18,15 +18,28 @@ https://github.com/firebase/firebase-js-sdk
 |  <b>function(app, ...)</b> |
 |  [getTelemetry(app)](./telemetry.md#gettelemetry_cf608e1) | Returns the default [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)<!-- -->. If no instance exists, initializes a new instance with the default settings. |
 |  <b>function(telemetry, ...)</b> |
-|  [captureError(telemetry, error)](./telemetry.md#captureerror_7c2d94e) | Enqueues an error to be uploaded to the Firebase Telemetry API. |
+|  [captureError(telemetry, error, attributes)](./telemetry.md#captureerror_862e6b3) | Enqueues an error to be uploaded to the Firebase Telemetry API. |
 |  [flush(telemetry)](./telemetry.md#flush_8975134) | Flushes all enqueued telemetry data immediately, instead of waiting for default batching. |
 
 ## Interfaces
 
 |  Interface | Description |
 |  --- | --- |
+|  [RequestErrorContext](./telemetry.requesterrorcontext.md#requesterrorcontext_interface) |  Copyright 2025 Google LLC<!-- -->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<!-- -->http://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. |
 |  [Telemetry](./telemetry.telemetry.md#telemetry_interface) | An instance of the Firebase Telemetry SDK.<!-- -->Do not create this instance directly. Instead, use [getTelemetry()](./telemetry.md#gettelemetry_cf608e1)<!-- -->. |
 
+## Variables
+
+|  Variable | Description |
+|  --- | --- |
+|  [nextOnRequestError](./telemetry.md#nextonrequesterror) | Automatically report uncaught errors from server routes to Firebase Telemetry. |
+
+## Type Aliases
+
+|  Type Alias | Description |
+|  --- | --- |
+|  [InstrumentationOnRequestError](./telemetry.md#instrumentationonrequesterror) |  |
+
 ## function(app, ...)
 
 ### getTelemetry(app) {:#gettelemetry_cf608e1}
@@ -61,22 +74,23 @@ const telemetry = getTelemetry(app);
 
 ## function(telemetry, ...)
 
-### captureError(telemetry, error) {:#captureerror_7c2d94e}
+### captureError(telemetry, error, attributes) {:#captureerror_862e6b3}
 
 Enqueues an error to be uploaded to the Firebase Telemetry API.
 
 <b>Signature:</b>
 
 ```typescript
-export declare function captureError(telemetry: Telemetry, error: unknown): void;
+export declare function captureError(telemetry: Telemetry, error: unknown, attributes?: AnyValueMap): void;
 ```
 
 #### Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  telemetry | [Telemetry](./telemetry.telemetry.md#telemetry_interface) | The [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance. |
-|  error | unknown | the caught exception, typically an  |
+|  error | unknown | The caught exception, typically an  |
+|  attributes | AnyValueMap | = Optional, arbitrary attributes to attach to the error log |
 
 <b>Returns:</b>
 
@@ -104,3 +118,33 @@ Promise&lt;void&gt;
 
 a promise which is resolved when all flushes are complete
 
+## nextOnRequestError
+
+Automatically report uncaught errors from server routes to Firebase Telemetry.
+
+<b>Signature:</b>
+
+```typescript
+nextOnRequestError: InstrumentationOnRequestError
+```
+
+### Example
+
+
+```javascript
+// In instrumentation.ts (https://nextjs.org/docs/app/guides/instrumentation):
+export { nextOnRequestError as onRequestError }  from 'firebase/telemetry'
+
+```
+
+## InstrumentationOnRequestError
+
+<b>Signature:</b>
+
+```typescript
+export type InstrumentationOnRequestError = (error: unknown, errorRequest: Readonly<{
+    path: string;
+    method: string;
+    headers: NodeJS.Dict<string | string[]>;
+}>, errorContext: Readonly<RequestErrorContext>) => void | Promise<void>;
+```

docs-devsite/telemetry.requesterrorcontext.md

@@ -0,0 +1,75 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# RequestErrorContext interface
+ Copyright 2025 Google LLC
+
+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
+
+http://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.
+
+<b>Signature:</b>
+
+```typescript
+export interface RequestErrorContext 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [renderSource](./telemetry.requesterrorcontext.md#requesterrorcontextrendersource) | 'react-server-components' \| 'react-server-components-payload' \| 'server-rendering' |  |
+|  [revalidateReason](./telemetry.requesterrorcontext.md#requesterrorcontextrevalidatereason) | 'on-demand' \| 'stale' \| undefined |  |
+|  [routePath](./telemetry.requesterrorcontext.md#requesterrorcontextroutepath) | string |  |
+|  [routerKind](./telemetry.requesterrorcontext.md#requesterrorcontextrouterkind) | 'Pages Router' \| 'App Router' |  |
+|  [routeType](./telemetry.requesterrorcontext.md#requesterrorcontextroutetype) | 'render' \| 'route' \| 'action' \| 'middleware' |  |
+
+## RequestErrorContext.renderSource
+
+<b>Signature:</b>
+
+```typescript
+renderSource?: 'react-server-components' | 'react-server-components-payload' | 'server-rendering';
+```
+
+## RequestErrorContext.revalidateReason
+
+<b>Signature:</b>
+
+```typescript
+revalidateReason: 'on-demand' | 'stale' | undefined;
+```
+
+## RequestErrorContext.routePath
+
+<b>Signature:</b>
+
+```typescript
+routePath: string;
+```
+
+## RequestErrorContext.routerKind
+
+<b>Signature:</b>
+
+```typescript
+routerKind: 'Pages Router' | 'App Router';
+```
+
+## RequestErrorContext.routeType
+
+<b>Signature:</b>
+
+```typescript
+routeType: 'render' | 'route' | 'action' | 'middleware';
+```

packages/telemetry/index.node.ts

@@ -24,8 +24,8 @@
 
 import { registerTelemetry } from './src/register.node';
 
-console.log('Hi Node.js Users!');
 registerTelemetry();
 
 export * from './src/api';
 export * from './src/public-types';
+export * from './src/next';

packages/telemetry/index.ts

@@ -21,3 +21,4 @@ registerTelemetry();
 
 export * from './src/api';
 export * from './src/public-types';
+export * from './src/next';

packages/telemetry/src/api.test.ts

@@ -146,6 +146,34 @@ describe('Top level API', () => {
         'logging.googleapis.com/spanId': `my-span`
       });
     });
+
+    it('should propagate custom attributes', () => {
+      const error = new Error('This is a test error');
+      error.stack = '...stack trace...';
+      error.name = 'TestError';
+
+      captureError(fakeTelemetry, error, {
+        strAttr: 'string attribute',
+        mapAttr: {
+          boolAttr: true,
+          numAttr: 2
+        },
+        arrAttr: [1, 2, 3]
+      });
+
+      expect(emittedLogs.length).to.equal(1);
+      const log = emittedLogs[0];
+      expect(log.attributes).to.deep.equal({
+        'error.type': 'TestError',
+        'error.stack': '...stack trace...',
+        strAttr: 'string attribute',
+        mapAttr: {
+          boolAttr: true,
+          numAttr: 2
+        },
+        arrAttr: [1, 2, 3]
+      });
+    });
   });
 
   describe('flush()', () => {

packages/telemetry/src/api.ts

@@ -60,9 +60,14 @@ export function getTelemetry(app: FirebaseApp = getApp()): Telemetry {
  * @public
  *
  * @param telemetry - The {@link Telemetry} instance.
- * @param error - the caught exception, typically an {@link Error}
+ * @param error - The caught exception, typically an {@link Error}
+ * @param attributes = Optional, arbitrary attributes to attach to the error log
  */
-export function captureError(telemetry: Telemetry, error: unknown): void {
+export function captureError(
+  telemetry: Telemetry,
+  error: unknown,
+  attributes?: AnyValueMap
+): void {
   const logger = telemetry.loggerProvider.getLogger('error-logger');
 
   const activeSpanContext = trace.getActiveSpan()?.spanContext();
@@ -77,30 +82,35 @@ export function captureError(telemetry: Telemetry, error: unknown): void {
     }
   }
 
+  const customAttributes = attributes || {};
+
   if (error instanceof Error) {
     logger.emit({
       severityNumber: SeverityNumber.ERROR,
       body: error.message,
       attributes: {
         'error.type': error.name || 'Error',
         'error.stack': error.stack || 'No stack trace available',
-        ...traceAttributes
+        ...traceAttributes,
+        ...customAttributes
       }
     });
   } else if (typeof error === 'string') {
     logger.emit({
       severityNumber: SeverityNumber.ERROR,
       body: error,
       attributes: {
-        ...traceAttributes
+        ...traceAttributes,
+        ...customAttributes
       }
     });
   } else {
     logger.emit({
       severityNumber: SeverityNumber.ERROR,
       body: `Unknown error type: ${typeof error}`,
       attributes: {
-        ...traceAttributes
+        ...traceAttributes,
+        ...customAttributes
       }
     });
   }