docs(observability): Fix MD linting

firebase · Feb 19, 2025 · 0501f1c · 0501f1c
1 parent 0a4d45b
commit 0501f1c
Show file tree

Hide file tree

Showing 6 changed files with 50 additions and 53 deletions.
diff --git a/docs/observability/advanced-configuration.md b/docs/observability/advanced-configuration.md
@@ -1,7 +1,6 @@
 # Advanced Configuration
 
-This guide focuses on advanced configuration options for deployed features using Firebase Genkit 
-Monitoring. Detailed descriptions of each configuration option can be found in our 
+This guide focuses on advanced configuration options for deployed features using the Firebase telemetry plugin. Detailed descriptions of each configuration option can be found in our 
 [JS API reference documentation](https://js.api.genkit.dev/interfaces/_genkit-ai_google-cloud.GcpTelemetryConfigOptions.html).
 
 This documentation will describe how to fine-tune which telemetry is collected, how often, and from what environments.
@@ -10,24 +9,24 @@ This documentation will describe how to fine-tune which telemetry is collected,
 
 Firebase Genkit Monitoring provides default options, out of the box, to get you up and running quickly.
 
-  * [autoInstrumentation](https://opentelemetry.io/docs/zero-code/js/): `true`
-  * [autoInstrumentationConfig](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-instrumentations-node/README.md#supported-instrumentations):
-    
-    ```
-    {
-      '@opentelemetry/instrumentation-dns': { enabled: false },
-    },
-    ```
-
-  * credentials: pulled from chosen [authentication strategy](./authentication.md)
-  * disableMetrics: `false`
-  * disableTraces: `false`
-  * disableLoggingInputAndOutput: `false`
-  * forceDevExport: `false`
-  * metricExportIntervalMillis: 5 minutes
-  * metricExportTimeoutMillis: 5 minutes
-  * projectId: pulled from [authentication strategy](./authentication.md)
-  * sampler: [AlwaysOnSampler](https://js.api.genkit.dev/interfaces/_genkit-ai_google-cloud.GcpTelemetryConfigOptions.html#sampler)
+* [autoInstrumentation](https://opentelemetry.io/docs/zero-code/js/): `true`
+* [autoInstrumentationConfig](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-instrumentations-node/README.md#supported-instrumentations):
+
+```typescript
+{
+  '@opentelemetry/instrumentation-dns': { enabled: false },
+},
+```
+
+* credentials: pulled from chosen [authentication strategy](./authentication.md)
+* disableMetrics: `false`
+* disableTraces: `false`
+* disableLoggingInputAndOutput: `false`
+* forceDevExport: `false`
+* metricExportIntervalMillis: 5 minutes
+* metricExportTimeoutMillis: 5 minutes
+* projectId: pulled from [authentication strategy](./authentication.md)
+* sampler: [AlwaysOnSampler](https://js.api.genkit.dev/interfaces/_genkit-ai_google-cloud.GcpTelemetryConfigOptions.html#sampler)
 
 ## Export local telemetry
 

diff --git a/docs/observability/authentication.md b/docs/observability/authentication.md
@@ -1,6 +1,6 @@
 # Authentication and authorization
 
-The Firebase telemetry plugin requires a Google Cloud project ID and application credentials. 
+The Firebase telemetry plugin requires a Google Cloud project ID and application credentials.
 
 If you don't have a Google Cloud project and account, you can set one up in the [Firebase Console](https://console.firebase.google.com/) or in the [Google Cloud Console](https://cloud.google.com). All Firebase project IDs are Google Cloud project IDs.
 
@@ -78,7 +78,7 @@ those credentials to your production environment.
 4. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable as the path to
    the credential file.
 
-    ```
+    ```posix-terminal
     GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"
     ```
 
@@ -89,7 +89,7 @@ Not sure which service account is the right one? See the [Find or create your se
 In some serverless environments, you may not be able to deploy a credential
 file.
 
-1. Follow the instructions to set up a 
+1. Follow the instructions to set up a
 [service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating).
 
 2. Ensure the service account has the following roles:
@@ -101,7 +101,7 @@ file.
 
 4. Assign the contents of the credential file to the `GCLOUD_SERVICE_ACCOUNT_CREDS` environment variable as follows:
 
-```
+```posix-terminal
 GCLOUD_SERVICE_ACCOUNT_CREDS='{
   "type": "service_account",
   "project_id": "your-project-id",
@@ -126,16 +126,16 @@ To find the appropriate service account:
 2. Select your project
 3. Find the appropriate service account. Common default service accounts are as follows:
 
-  - Firebase functions & Cloud Run
+- Firebase functions & Cloud Run
 
     <code><var>PROJECT ID</var>[email protected]</code>
 
-  - App Engine
+- App Engine
 
     <code><var>PROJECT ID</var>@appspot.gserviceaccount.com</code>
 
-  - App Hosting
+- App Hosting
 
     <code>firebase-app-hosting-compute@<var>PROJECT ID</var>.iam.gserviceaccount.com</code>
 
-If you are deploying outside of the Google ecosystem or don't want to use a default service account, you can [create a service account](https://cloud.google.com/iam/docs/service-accounts-create#creating) in the Google Cloud console. 
+If you are deploying outside of the Google ecosystem or don't want to use a default service account, you can [create a service account](https://cloud.google.com/iam/docs/service-accounts-create#creating) in the Google Cloud console.
diff --git a/docs/observability/getting-started.md b/docs/observability/getting-started.md
@@ -41,12 +41,11 @@ and on the Google Cloud Console.
    2. [Deploy flows using Cloud Run](../cloud-run)
    3. [Deploy flows to any Node.js platform](../deploy-node)
 
-
 ## Step 1. Add the Firebase plugin
 
 Install the `@genkit-ai/firebase` plugin in your project:
 
-```
+```posix-terminal
 npm i –save @genkit-ai/firebase
 ```
 
@@ -95,15 +94,16 @@ dashboard.
 2. Use your service account to authenticate and test your configuration.
 
    Tip: In order to impersonate the service account, you will need to have
-   the `roles/iam.serviceAccountTokenCreator` [IAM role](https://console.
+   the `roles/iam.serviceAccountTokenCreator` [IAM role](<https://console>.
    cloud.google.com/iam-admin/iam) applied to your user account.
 
    With the
    [Google Cloud CLI tool](https://cloud.google.com/sdk/docs/install?authuser=0), authenticate using the service account:
 
-    ```
+    ```posix-terminal
     gcloud auth application-default login --impersonate-service-account <SERVICE_ACCT_EMAIL>
     ```
+
 3. Run and invoke your Genkit feature, and then view metrics on the
    [Genkit Monitoring dashboard](https://console.firebase.google.com/project/_/genai_monitoring).
    Allow for up to 5 minutes to collect the first metric. You can reduce this

diff --git a/docs/observability/telemetry-collection.md b/docs/observability/telemetry-collection.md
@@ -45,7 +45,6 @@ Each feature metric contains the following dimensions:
 | source        | The Genkit source language. Eg. 'ts'                                             |
 | sourceVersion | The Genkit framework version                                                     |
 
-
 ### Action metrics
 
 Actions represent a generic step of execution within Genkit. Each of these steps
@@ -102,7 +101,7 @@ Each generate metric contains the following dimensions:
 
 ## Traces
 
-All Genkit actions are automatically instrumented to provide detailed traces for your AI features. Locally, traces are visible in 
+All Genkit actions are automatically instrumented to provide detailed traces for your AI features. Locally, traces are visible in
 the Developer UI. For deployed apps enable Firebase Genkit Monitoring to get the same level of visibility.
 
 The following sections describe what trace attributes you can expect based on the Genkit action type for a particular span in the
@@ -130,7 +129,7 @@ Root spans have special attributes to help disambiguate the state attributes for
 | genkit/state            | The state of this span's execution as `success` or `error`.                                                                       |
 | genkit/type             | The type of Genkit primitive that corresponds to this span. For flows, this will be `action`.                                     |
 
-### Util 
+### Util
 
 | Attribute name          | Description                                                                                                                       |
 | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -146,7 +145,7 @@ Root spans have special attributes to help disambiguate the state attributes for
 | Attribute name          | Description                                                                                                                       |
 | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
 | genkit/input            | The input to the model. This will always be `<redacted>` because of trace attribute size limits.                                  |
-| genkit/metadata/subtype | The type of Genkit action. For moedles it will be `model`.                                                                        |
+| genkit/metadata/subtype | The type of Genkit action. For models it will be `model`.                                                                         |
 | genkit/model            | The name of the model.                                                                                                            |
 | genkit/name             | The name of this Genkit action. In this case the name of the model.                                                               |
 | genkit/output           | The output generated by the model. This will always be `<redacted>` because of trace attribute size limits.                       |
@@ -156,13 +155,15 @@ Root spans have special attributes to help disambiguate the state attributes for
 
 ### Tool
 
-genkit/input	<redacted>
-genkit/metadata/subtype	tool
-genkit/name	getWeather
-genkit/output	<redacted>
-genkit/path	/{flowTouristActivitiesStreaming,t:flow}/{generate,t:util}/{generate,t:util}/{generate,t:util}/{getWeather,t:action,s:tool}
-genkit/state	success
-genkit/type	action
+| Attribute name          | Description                                                                                                                       |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| genkit/input            | The input to the model. This will always be `<redacted>` because of trace attribute size limits.                                  |
+| genkit/metadata/subtype | The type of Genkit action. For tools it will be `tool`.                                                                           |
+| genkit/name             | The name of this Genkit action. In this case the name of the model.                                                               |
+| genkit/output           | The output generated by the model. This will always be `<redacted>` because of trace attribute size limits.                       |
+| genkit/path             | The fully qualified execution path that lead to this step in the trace, including type information.                               |
+| genkit/state            | The state of this span's execution as `success` or `error`.                                                                       |
+| genkit/type             | The type of Genkit primitive that corresponds to this span. For flows, this will be `action`.                                     |
 
 ## Logs
 
@@ -236,15 +237,15 @@ Metadata:
 | totalCandidates * (deprecated) | Total number of candidates generated as output. For single-candidate messages, this will always be 1.                                                           |
 | totalParts *                   | Total number of parts for this message. For single-part messages, this will always be 1.                                                                        |
 
-(*) Starred items are only present on Input logs for model interactions.
+(*) Starred items are only present on Output logs for model interactions.
 
 ### Config
 
 JSON payload:
 
 | Field name        | Description                                                                                                                       |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| message           | `[genkit] Config[<path>, <featureName>` including `(message X of N)` for multi-part messages                                       |
+| message           | `[genkit] Config[<path>, <featureName>`                                                                                           |
 | metadata          | Additional context including the input message sent to the action                                                                 |
 
 Metadata:
@@ -261,13 +262,11 @@ Metadata:
 
 ### Paths
 
-Path logs are only present when genkit is used with a 
-
 JSON payload:
 
 | Field name        | Description                                                                                                                       |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| message           | `[genkit] Input[<path>, <featureName>` including `(message X of N)` for multi-part messages                                       |
+| message           | `[genkit] Paths[<path>, <featureName>`                                                                                            |
 | metadata          | Additional context including the input message sent to the action                                                                 |
 
 Metadata:

diff --git a/docs/observability/troubleshooting.md b/docs/observability/troubleshooting.md
@@ -39,7 +39,7 @@
    serviceAccountTokenCreator` IAM role applied to your user account in order
    to impersonate service accounts:
 
-    ```
+    ```posix-terminal
     gcloud auth application-default login --impersonate-service-account <SERVICE_ACCT_EMAIL>
     ```
 
@@ -57,4 +57,4 @@ If higher reliability is important to you, consider changing
 [CPU allocation](https://cloud.google.com/run/docs/configuring/cpu-allocation)
 to **always allocated** in the Google Cloud Console.
 
-Note: The **always allocated** setting impacts pricing.
+Note: The **always allocated** setting impacts pricing.
diff --git a/docs/plugins/firebase.md b/docs/plugins/firebase.md
@@ -275,7 +275,7 @@ section of the Firestore docs.
 
   The command looks like the following:
 
-  ```
+  ```posix-terminal
   gcloud alpha firestore indexes composite create --project=your-project-id \
     --collection-group=yourCollectionName --query-scope=COLLECTION \
     --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=yourEmbeddingField
@@ -284,7 +284,6 @@ section of the Firestore docs.
   However, the correct indexing configuration depends on the queries you
   make and the embedding model you're using.
 
-
 - Alternatively, call `ai.retrieve()` and Firestore will throw an error with
   the correct command to create the index.
 
@@ -327,6 +326,6 @@ export const example = onCallGenkit({ secrets: [apiKey] }, exampleFlow);
 
 Deploy your flow using the Firebase CLI:
 
-```
+```posix-terminal
 firebase deploy --only functions
 ```