Skip to content

Commit 484c8a5

Browse files
tonybaroneeehsubox76
tonybaroneee
and
hsubox76
authored
Add ref doc generation to telemetry package (#9228)
* Add ref doc generation to `telemetry` package * fix docs * Rename index to register * Run `typings:public` script to generate correct `typings` value * Update _toc.yaml * add api-report run to yarn build --------- Co-authored-by: Christina Holland <[email protected]>
1 parent 6993a18 commit 484c8a5

File tree

12 files changed

+207
-6
lines changed

12 files changed

+207
-6
lines changed

‎common/api-review/telemetry.api.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## API Report File for "@firebase/telemetry"
2+
3+
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
4+
5+
```ts
6+
7+
import { FirebaseApp } from '@firebase/app';
8+
import { LoggerProvider } from '@opentelemetry/sdk-logs';
9+
10+
// @public
11+
export function captureError(telemetry: Telemetry, error: unknown): void;
12+
13+
// @public
14+
export function flush(telemetry: Telemetry): Promise<void>;
15+
16+
// @public
17+
export function getTelemetry(app?: FirebaseApp): Telemetry;
18+
19+
// @public
20+
export interface Telemetry {
21+
app: FirebaseApp;
22+
loggerProvider: LoggerProvider;
23+
}
24+
25+
26+
// (No @packageDocumentation comment for this package)
27+
28+
```

‎docs-devsite/_toc.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -648,3 +648,8 @@ toc:
648648
path: /docs/reference/js/storage.uploadtask.md
649649
- title: UploadTaskSnapshot
650650
path: /docs/reference/js/storage.uploadtasksnapshot.md
651+
- title: telemetry
652+
path: /docs/reference/js/telemetry.md
653+
section:
654+
- title: Telemetry
655+
path: /docs/reference/js/telemetry.telemetry.md

‎docs-devsite/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,5 @@ https://github.com/firebase/firebase-js-sdk
2828
| [@firebase/performance](./performance.md#performance_package) | The Firebase Performance Monitoring Web SDK. This SDK does not work in a Node.js environment. |
2929
| [@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. |
3030
| [@firebase/storage](./storage.md#storage_package) | Cloud Storage for Firebase |
31+
| [@firebase/telemetry](./telemetry.md#telemetry_package) | |
3132

‎docs-devsite/telemetry.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
Project: /docs/reference/js/_project.yaml
2+
Book: /docs/reference/_book.yaml
3+
page_type: reference
4+
5+
{% comment %}
6+
DO NOT EDIT THIS FILE!
7+
This is generated by the JS SDK team, and any local changes will be
8+
overwritten. Changes should be made in the source code at
9+
https://github.com/firebase/firebase-js-sdk
10+
{% endcomment %}
11+
12+
# telemetry package
13+
14+
## Functions
15+
16+
| Function | Description |
17+
| --- | --- |
18+
| <b>function(app, ...)</b> |
19+
| [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. |
20+
| <b>function(telemetry, ...)</b> |
21+
| [captureError(telemetry, error)](./telemetry.md#captureerror_7c2d94e) | Enqueues an error to be uploaded to the Firebase Telemetry API. |
22+
| [flush(telemetry)](./telemetry.md#flush_8975134) | Flushes all enqueued telemetry data immediately, instead of waiting for default batching. |
23+
24+
## Interfaces
25+
26+
| Interface | Description |
27+
| --- | --- |
28+
| [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)<!-- -->. |
29+
30+
## function(app, ...)
31+
32+
### getTelemetry(app) {:#gettelemetry_cf608e1}
33+
34+
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.
35+
36+
<b>Signature:</b>
37+
38+
```typescript
39+
export declare function getTelemetry(app?: FirebaseApp): Telemetry;
40+
```
41+
42+
#### Parameters
43+
44+
| Parameter | Type | Description |
45+
| --- | --- | --- |
46+
| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. |
47+
48+
<b>Returns:</b>
49+
50+
[Telemetry](./telemetry.telemetry.md#telemetry_interface)
51+
52+
The default [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance for the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)<!-- -->.
53+
54+
### Example
55+
56+
57+
```javascript
58+
const telemetry = getTelemetry(app);
59+
60+
```
61+
62+
## function(telemetry, ...)
63+
64+
### captureError(telemetry, error) {:#captureerror_7c2d94e}
65+
66+
Enqueues an error to be uploaded to the Firebase Telemetry API.
67+
68+
<b>Signature:</b>
69+
70+
```typescript
71+
export declare function captureError(telemetry: Telemetry, error: unknown): void;
72+
```
73+
74+
#### Parameters
75+
76+
| Parameter | Type | Description |
77+
| --- | --- | --- |
78+
| telemetry | [Telemetry](./telemetry.telemetry.md#telemetry_interface) | The [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance. |
79+
| error | unknown | the caught exception, typically an |
80+
81+
<b>Returns:</b>
82+
83+
void
84+
85+
### flush(telemetry) {:#flush_8975134}
86+
87+
Flushes all enqueued telemetry data immediately, instead of waiting for default batching.
88+
89+
<b>Signature:</b>
90+
91+
```typescript
92+
export declare function flush(telemetry: Telemetry): Promise<void>;
93+
```
94+
95+
#### Parameters
96+
97+
| Parameter | Type | Description |
98+
| --- | --- | --- |
99+
| telemetry | [Telemetry](./telemetry.telemetry.md#telemetry_interface) | The [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance. |
100+
101+
<b>Returns:</b>
102+
103+
Promise&lt;void&gt;
104+
105+
a promise which is resolved when all flushes are complete
106+

‎docs-devsite/telemetry.telemetry.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
Project: /docs/reference/js/_project.yaml
2+
Book: /docs/reference/_book.yaml
3+
page_type: reference
4+
5+
{% comment %}
6+
DO NOT EDIT THIS FILE!
7+
This is generated by the JS SDK team, and any local changes will be
8+
overwritten. Changes should be made in the source code at
9+
https://github.com/firebase/firebase-js-sdk
10+
{% endcomment %}
11+
12+
# Telemetry interface
13+
An instance of the Firebase Telemetry SDK.
14+
15+
Do not create this instance directly. Instead, use [getTelemetry()](./telemetry.md#gettelemetry_cf608e1)<!-- -->.
16+
17+
<b>Signature:</b>
18+
19+
```typescript
20+
export interface Telemetry
21+
```
22+
23+
## Properties
24+
25+
| Property | Type | Description |
26+
| --- | --- | --- |
27+
| [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. |
28+
| [loggerProvider](./telemetry.telemetry.md#telemetryloggerprovider) | LoggerProvider | The this [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance uses. |
29+
30+
## Telemetry.app
31+
32+
The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance is associated with.
33+
34+
<b>Signature:</b>
35+
36+
```typescript
37+
app: FirebaseApp;
38+
```
39+
40+
## Telemetry.loggerProvider
41+
42+
The this [Telemetry](./telemetry.telemetry.md#telemetry_interface) instance uses.
43+
44+
<b>Signature:</b>
45+
46+
```typescript
47+
loggerProvider: LoggerProvider;
48+
```

‎packages/telemetry/api-extractor.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"extends": "../../config/api-extractor.json",
3+
// Point it to your entry point d.ts file.
4+
"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
5+
"dtsRollup": {
6+
"enabled": true,
7+
"untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
8+
"betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts"
9+
}
10+
}

‎packages/telemetry/index.node.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
* just use index.ts
2323
*/
2424

25-
import { registerTelemetry } from './src/index.node';
25+
import { registerTelemetry } from './src/register.node';
2626

2727
console.log('Hi Node.js Users!');
2828
registerTelemetry();

‎packages/telemetry/index.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
* limitations under the License.
1616
*/
1717

18-
import { registerTelemetry } from './src';
18+
import { registerTelemetry } from './src/register';
1919

2020
registerTelemetry();
2121

‎packages/telemetry/package.json

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,17 @@
2727
"scripts": {
2828
"lint": "eslint -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'",
2929
"lint:fix": "eslint --fix -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'",
30-
"build": "rollup -c",
30+
"build": "rollup -c && yarn api-report",
3131
"build:deps": "lerna run --scope @firebase/telemetry --include-dependencies build",
3232
"dev": "rollup -c -w",
3333
"test": "run-p --npm-path npm lint test:all",
3434
"test:ci": "node ../../scripts/run_tests_in_ci.js -s test:all",
3535
"test:all": "run-p --npm-path npm test:browser test:node",
3636
"test:browser": "karma start",
3737
"test:node": "TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' nyc --reporter lcovonly -- mocha src/**/*.test.* --config ../../config/mocharc.node.js",
38-
"trusted-type-check": "tsec -p tsconfig.json --noEmit"
38+
"trusted-type-check": "tsec -p tsconfig.json --noEmit",
39+
"api-report": "api-extractor run --local --verbose",
40+
"typings:public": "node ../../scripts/build/use_typings.js ./dist/telemetry-public.d.ts"
3941
},
4042
"peerDependencies": {
4143
"@firebase/app": "0.x",
@@ -67,7 +69,7 @@
6769
"bugs": {
6870
"url": "https://github.com/firebase/firebase-js-sdk/issues"
6971
},
70-
"typings": "dist/index.d.ts",
72+
"typings": "./dist/telemetry-public.d.ts",
7173
"nyc": {
7274
"extension": [
7375
".ts"

‎packages/telemetry/src/index.node.ts renamed to ‎packages/telemetry/src/register.node.ts

File renamed without changes.

0 commit comments

Comments
 (0)