From c13c5ad26b79f3a2cdac3d8f62b6a0df24fb9839 Mon Sep 17 00:00:00 2001 From: Anthony Barone Date: Tue, 26 Aug 2025 18:16:51 +0000 Subject: [PATCH 1/6] Add ref doc generation to `telemetry` package --- common/api-review/telemetry.api.md | 16 ++++++++++ docs-devsite/_toc.yaml | 3 ++ docs-devsite/index.md | 1 + docs-devsite/telemetry.md | 44 +++++++++++++++++++++++++++ packages/telemetry/api-extractor.json | 10 ++++++ packages/telemetry/package.json | 6 ++-- scripts/docgen/docgen.ts | 3 +- 7 files changed, 80 insertions(+), 3 deletions(-) create mode 100644 common/api-review/telemetry.api.md create mode 100644 docs-devsite/telemetry.md create mode 100644 packages/telemetry/api-extractor.json diff --git a/common/api-review/telemetry.api.md b/common/api-review/telemetry.api.md new file mode 100644 index 00000000000..f11d225b175 --- /dev/null +++ b/common/api-review/telemetry.api.md @@ -0,0 +1,16 @@ +## API Report File for "@firebase/telemetry" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +// @public (undocumented) +export function registerTelemetry(): void; + +// @public (undocumented) +export function testFxn(): number; + + +// (No @packageDocumentation comment for this package) + +``` diff --git a/docs-devsite/_toc.yaml b/docs-devsite/_toc.yaml index da7c2500894..582aeb7a6d9 100644 --- a/docs-devsite/_toc.yaml +++ b/docs-devsite/_toc.yaml @@ -648,3 +648,6 @@ toc: path: /docs/reference/js/storage.uploadtask.md - title: UploadTaskSnapshot path: /docs/reference/js/storage.uploadtasksnapshot.md +- title: telemetry + path: /docs/reference/js/telemetry.md + section: [] diff --git a/docs-devsite/index.md b/docs-devsite/index.md index 47ec0be16ba..a52937d582c 100644 --- a/docs-devsite/index.md +++ b/docs-devsite/index.md @@ -28,4 +28,5 @@ https://github.com/firebase/firebase-js-sdk | [@firebase/performance](./performance.md#performance_package) | The Firebase Performance Monitoring Web SDK. This SDK does not work in a Node.js environment. | | [@firebase/remote-config](./remote-config.md#remote-config_package) | The Firebase Remote Config Web SDK. This SDK does not work in a Node.js environment. | | [@firebase/storage](./storage.md#storage_package) | Cloud Storage for Firebase | +| [@firebase/telemetry](./telemetry.md#telemetry_package) | | diff --git a/docs-devsite/telemetry.md b/docs-devsite/telemetry.md new file mode 100644 index 00000000000..3cee90fefb1 --- /dev/null +++ b/docs-devsite/telemetry.md @@ -0,0 +1,44 @@ +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 %} + +# telemetry package + +## Functions + +| Function | Description | +| --- | --- | +| [registerTelemetry()](./telemetry.md#registertelemetry) | | +| [testFxn()](./telemetry.md#testfxn) | | + +## function() + +### registerTelemetry() {:#registertelemetry} + +Signature: + +```typescript +export declare function registerTelemetry(): void; +``` +Returns: + +void + +### testFxn() {:#testfxn} + +Signature: + +```typescript +export declare function testFxn(): number; +``` +Returns: + +number + diff --git a/packages/telemetry/api-extractor.json b/packages/telemetry/api-extractor.json new file mode 100644 index 00000000000..cf157a03ff7 --- /dev/null +++ b/packages/telemetry/api-extractor.json @@ -0,0 +1,10 @@ +{ + "extends": "../../config/api-extractor.json", + // Point it to your entry point d.ts file. + "mainEntryPointFilePath": "/dist/src/index.d.ts", + "dtsRollup": { + "enabled": true, + "untrimmedFilePath": "/dist/.d.ts", + "betaTrimmedFilePath": "/dist/-public.d.ts" + } +} diff --git a/packages/telemetry/package.json b/packages/telemetry/package.json index 87c9f2b1c11..838894491ac 100644 --- a/packages/telemetry/package.json +++ b/packages/telemetry/package.json @@ -35,7 +35,9 @@ "test:all": "run-p --npm-path npm test:browser test:node", "test:browser": "karma start", "test:node": "TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' nyc --reporter lcovonly -- mocha src/**/*.test.* --config ../../config/mocharc.node.js", - "trusted-type-check": "tsec -p tsconfig.json --noEmit" + "trusted-type-check": "tsec -p tsconfig.json --noEmit", + "api-report": "api-extractor run --local --verbose && ts-node-script ../../repo-scripts/prune-dts/prune-dts.ts --input dist/telemetry-public.d.ts --output dist/telemetry-public.d.ts", + "typings:public": "node ../../scripts/build/use_typings.js ./dist/telemetry-public.d.ts" }, "peerDependencies": { "@firebase/app": "0.x", @@ -67,7 +69,7 @@ "bugs": { "url": "https://github.com/firebase/firebase-js-sdk/issues" }, - "typings": "dist/index.d.ts", + "typings": "dist/src/index.d.ts", "nyc": { "extension": [ ".ts" diff --git a/scripts/docgen/docgen.ts b/scripts/docgen/docgen.ts index af105ef65f6..936eb0d69ca 100644 --- a/scripts/docgen/docgen.ts +++ b/scripts/docgen/docgen.ts @@ -60,7 +60,8 @@ const PREFERRED_PARAMS = [ 'performance', 'remoteConfig', 'storage', - 'ai' + 'ai', + 'telemetry' ]; let authApiReportOriginal: string; From 191b8640b0288f7ad109f5098f35c66d0f1cbf2a Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Tue, 26 Aug 2025 12:51:07 -0700 Subject: [PATCH 2/6] fix docs --- common/api-review/telemetry.api.md | 20 +++++-- docs-devsite/telemetry.md | 78 ++++++++++++++++++++++++--- docs-devsite/telemetry.telemetry.md | 48 +++++++++++++++++ packages/telemetry/api-extractor.json | 2 +- packages/telemetry/package.json | 4 +- 5 files changed, 137 insertions(+), 15 deletions(-) create mode 100644 docs-devsite/telemetry.telemetry.md diff --git a/common/api-review/telemetry.api.md b/common/api-review/telemetry.api.md index f11d225b175..6c9dcdb93dc 100644 --- a/common/api-review/telemetry.api.md +++ b/common/api-review/telemetry.api.md @@ -4,11 +4,23 @@ ```ts -// @public (undocumented) -export function registerTelemetry(): void; +import { FirebaseApp } from '@firebase/app'; +import { LoggerProvider } from '@opentelemetry/sdk-logs'; -// @public (undocumented) -export function testFxn(): number; +// @public +export function captureError(telemetry: Telemetry, error: unknown): void; + +// @public +export function flush(telemetry: Telemetry): Promise; + +// @public +export function getTelemetry(app?: FirebaseApp): Telemetry; + +// @public +export interface Telemetry { + app: FirebaseApp; + loggerProvider: LoggerProvider; +} // (No @packageDocumentation comment for this package) diff --git a/docs-devsite/telemetry.md b/docs-devsite/telemetry.md index 3cee90fefb1..d09f314a67e 100644 --- a/docs-devsite/telemetry.md +++ b/docs-devsite/telemetry.md @@ -15,30 +15,92 @@ https://github.com/firebase/firebase-js-sdk | Function | Description | | --- | --- | -| [registerTelemetry()](./telemetry.md#registertelemetry) | | -| [testFxn()](./telemetry.md#testfxn) | | +| function(app, ...) | +| [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. | +| function(telemetry, ...) | +| [captureError(telemetry, error)](./telemetry.md#captureerror_7c2d94e) | 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. | -## function() +## Interfaces -### registerTelemetry() {:#registertelemetry} +| Interface | Description | +| --- | --- | +| [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). | + +## function(app, ...) + +### getTelemetry(app) {:#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. Signature: ```typescript -export declare function registerTelemetry(): void; +export declare function getTelemetry(app?: FirebaseApp): Telemetry; ``` + +#### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | + +Returns: + +[Telemetry](./telemetry.telemetry.md#telemetry_interface) + +The default [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance for the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). + +### Example + + +```javascript +const telemetry = getTelemetry(app); + +``` + +## function(telemetry, ...) + +### captureError(telemetry, error) {:#captureerror_7c2d94e} + +Enqueues an error to be uploaded to the Firebase Telemetry API. + +Signature: + +```typescript +export declare function captureError(telemetry: Telemetry, error: unknown): 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 | + Returns: void -### testFxn() {:#testfxn} +### flush(telemetry) {:#flush_8975134} + +Flushes all enqueued telemetry data immediately, instead of waiting for default batching. Signature: ```typescript -export declare function testFxn(): number; +export declare function flush(telemetry: Telemetry): Promise; ``` + +#### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| telemetry | [Telemetry](./telemetry.telemetry.md#telemetry_interface) | The [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance. | + Returns: -number +Promise<void> + +a promise which is resolved when all flushes are complete diff --git a/docs-devsite/telemetry.telemetry.md b/docs-devsite/telemetry.telemetry.md new file mode 100644 index 00000000000..3e7396f79d6 --- /dev/null +++ b/docs-devsite/telemetry.telemetry.md @@ -0,0 +1,48 @@ +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 %} + +# Telemetry interface +An instance of the Firebase Telemetry SDK. + +Do not create this instance directly. Instead, use [getTelemetry()](./telemetry.md#gettelemetry_cf608e1). + +Signature: + +```typescript +export interface Telemetry +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./telemetry.telemetry.md#telemetryapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance is associated with. | +| [loggerProvider](./telemetry.telemetry.md#telemetryloggerprovider) | LoggerProvider | The this [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance uses. | + +## Telemetry.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` + +## Telemetry.loggerProvider + +The this [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance uses. + +Signature: + +```typescript +loggerProvider: LoggerProvider; +``` diff --git a/packages/telemetry/api-extractor.json b/packages/telemetry/api-extractor.json index cf157a03ff7..af30d031b7f 100644 --- a/packages/telemetry/api-extractor.json +++ b/packages/telemetry/api-extractor.json @@ -1,7 +1,7 @@ { "extends": "../../config/api-extractor.json", // Point it to your entry point d.ts file. - "mainEntryPointFilePath": "/dist/src/index.d.ts", + "mainEntryPointFilePath": "/dist/index.d.ts", "dtsRollup": { "enabled": true, "untrimmedFilePath": "/dist/.d.ts", diff --git a/packages/telemetry/package.json b/packages/telemetry/package.json index 838894491ac..ccabc5b1abc 100644 --- a/packages/telemetry/package.json +++ b/packages/telemetry/package.json @@ -36,7 +36,7 @@ "test:browser": "karma start", "test:node": "TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' nyc --reporter lcovonly -- mocha src/**/*.test.* --config ../../config/mocharc.node.js", "trusted-type-check": "tsec -p tsconfig.json --noEmit", - "api-report": "api-extractor run --local --verbose && ts-node-script ../../repo-scripts/prune-dts/prune-dts.ts --input dist/telemetry-public.d.ts --output dist/telemetry-public.d.ts", + "api-report": "api-extractor run --local --verbose", "typings:public": "node ../../scripts/build/use_typings.js ./dist/telemetry-public.d.ts" }, "peerDependencies": { @@ -69,7 +69,7 @@ "bugs": { "url": "https://github.com/firebase/firebase-js-sdk/issues" }, - "typings": "dist/src/index.d.ts", + "typings": "dist/index.d.ts", "nyc": { "extension": [ ".ts" From b6e3a59e4a9e8623b832b6ee85f3fd7a4ab7d68c Mon Sep 17 00:00:00 2001 From: Anthony Barone Date: Tue, 26 Aug 2025 20:03:54 +0000 Subject: [PATCH 3/6] Rename index to register --- packages/telemetry/index.node.ts | 2 +- packages/telemetry/index.ts | 2 +- packages/telemetry/src/{index.node.ts => register.node.ts} | 0 packages/telemetry/src/{index.ts => register.ts} | 0 4 files changed, 2 insertions(+), 2 deletions(-) rename packages/telemetry/src/{index.node.ts => register.node.ts} (100%) rename packages/telemetry/src/{index.ts => register.ts} (100%) diff --git a/packages/telemetry/index.node.ts b/packages/telemetry/index.node.ts index 409c7d50a07..a8f917bcb3f 100644 --- a/packages/telemetry/index.node.ts +++ b/packages/telemetry/index.node.ts @@ -22,7 +22,7 @@ * just use index.ts */ -import { registerTelemetry } from './src/index.node'; +import { registerTelemetry } from './src/register.node'; console.log('Hi Node.js Users!'); registerTelemetry(); diff --git a/packages/telemetry/index.ts b/packages/telemetry/index.ts index 28fb9e7762a..de61416f514 100644 --- a/packages/telemetry/index.ts +++ b/packages/telemetry/index.ts @@ -15,7 +15,7 @@ * limitations under the License. */ -import { registerTelemetry } from './src'; +import { registerTelemetry } from './src/register'; registerTelemetry(); diff --git a/packages/telemetry/src/index.node.ts b/packages/telemetry/src/register.node.ts similarity index 100% rename from packages/telemetry/src/index.node.ts rename to packages/telemetry/src/register.node.ts diff --git a/packages/telemetry/src/index.ts b/packages/telemetry/src/register.ts similarity index 100% rename from packages/telemetry/src/index.ts rename to packages/telemetry/src/register.ts From a0182f2850b4f167fd081a1d473305d77849b115 Mon Sep 17 00:00:00 2001 From: Anthony Barone Date: Tue, 26 Aug 2025 20:13:41 +0000 Subject: [PATCH 4/6] Run `typings:public` script to generate correct `typings` value --- packages/telemetry/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/telemetry/package.json b/packages/telemetry/package.json index ccabc5b1abc..89ed40f91eb 100644 --- a/packages/telemetry/package.json +++ b/packages/telemetry/package.json @@ -69,7 +69,7 @@ "bugs": { "url": "https://github.com/firebase/firebase-js-sdk/issues" }, - "typings": "dist/index.d.ts", + "typings": "./dist/telemetry-public.d.ts", "nyc": { "extension": [ ".ts" From 6db6dff3298f5ee9e4dd490ef4b3ff9783e56f11 Mon Sep 17 00:00:00 2001 From: Anthony Barone Date: Tue, 26 Aug 2025 20:17:16 +0000 Subject: [PATCH 5/6] Update _toc.yaml --- docs-devsite/_toc.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs-devsite/_toc.yaml b/docs-devsite/_toc.yaml index 582aeb7a6d9..d07bb66b847 100644 --- a/docs-devsite/_toc.yaml +++ b/docs-devsite/_toc.yaml @@ -650,4 +650,6 @@ toc: path: /docs/reference/js/storage.uploadtasksnapshot.md - title: telemetry path: /docs/reference/js/telemetry.md - section: [] + section: + - title: Telemetry + path: /docs/reference/js/telemetry.telemetry.md From 8a2a29df2df4fb46c5b9068636b853fd858e676c Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Tue, 26 Aug 2025 15:41:35 -0700 Subject: [PATCH 6/6] add api-report run to yarn build --- packages/telemetry/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/telemetry/package.json b/packages/telemetry/package.json index 89ed40f91eb..8856f96e408 100644 --- a/packages/telemetry/package.json +++ b/packages/telemetry/package.json @@ -27,7 +27,7 @@ "scripts": { "lint": "eslint -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'", "lint:fix": "eslint --fix -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'", - "build": "rollup -c", + "build": "rollup -c && yarn api-report", "build:deps": "lerna run --scope @firebase/telemetry --include-dependencies build", "dev": "rollup -c -w", "test": "run-p --npm-path npm lint test:all",