diff --git a/common/api-review/telemetry.api.md b/common/api-review/telemetry.api.md new file mode 100644 index 00000000000..6c9dcdb93dc --- /dev/null +++ b/common/api-review/telemetry.api.md @@ -0,0 +1,28 @@ +## API Report File for "@firebase/telemetry" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +import { FirebaseApp } from '@firebase/app'; +import { LoggerProvider } from '@opentelemetry/sdk-logs'; + +// @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/_toc.yaml b/docs-devsite/_toc.yaml index da7c2500894..d07bb66b847 100644 --- a/docs-devsite/_toc.yaml +++ b/docs-devsite/_toc.yaml @@ -648,3 +648,8 @@ 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: + - title: Telemetry + path: /docs/reference/js/telemetry.telemetry.md 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..d09f314a67e --- /dev/null +++ b/docs-devsite/telemetry.md @@ -0,0 +1,106 @@ +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 | +| --- | --- | +| 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. | + +## Interfaces + +| 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 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 + +### flush(telemetry) {:#flush_8975134} + +Flushes all enqueued telemetry data immediately, instead of waiting for default batching. + +Signature: + +```typescript +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: + +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 new file mode 100644 index 00000000000..af30d031b7f --- /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/index.d.ts", + "dtsRollup": { + "enabled": true, + "untrimmedFilePath": "/dist/.d.ts", + "betaTrimmedFilePath": "/dist/-public.d.ts" + } +} 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/package.json b/packages/telemetry/package.json index 87c9f2b1c11..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", @@ -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", + "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/telemetry-public.d.ts", "nyc": { "extension": [ ".ts" 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 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;