# Mod Product Telemetry ### Pre-Configured Telemetry Options For [deployed mods](https://docs.pixiebrix.com/deploying-mods), PixieBrix automatically captures the following telemetry: * Starter Brick runs * Starter Brick error telemetry The captured telemetry is available in Deployment Detail screen under Engagement and Errors, respectively. #### Starter Brick Telemetry Mode Trigger Starter Bricks include a Telemetry Mode option that controls which events and errors are reported: * Report All Events and Errors * Report First Event and Error (default): best for automatic triggers that run on specific sites/in specific situations * Report First Error: best for automated triggers that run on all sites * Never Report Events or Errors The "First" options correspond to the first run/event for a page visit.

Trigger Starter Brick Telemetry Mode

#### Run with Async Mod Variable Telemetry Mode The "Run with Async Mod Variable" runs one or more bricks and stores the result or error to a mod variable. The brick itself does not error. Therefore, the brick has a Telemetry Mode field for optionally reporting errors to mod error telemetry:

Run with Async Mod Variable Telemetry Mode

For privacy, the default Starter Brick event telemetry only includes the name of the starter brick, time, and user. To capture more information or to create a ### Creating Custom Telemetry Events To capture custom product telemetry with attributes to a team database for reporting, use the Record Product Telemetry to DB brick. #### Record Product Telemetry to DB Brick PixieBrix makes a `@pixies/telemetry/record` brick available for recording product telemetry to a team database. The brick runs asynchronously, so it does not block mod execution. The brick takes the following inputs: * **Telemetry Database**: the database to use to store telemetry events. Per best practice, use a database defined via a [Mod Option](https://docs.pixiebrix.com/developing-mods/sharing-mods/exposing-activation-time-mod-options) so you can use a different Telemetry Database for each environment (development vs. testing vs production) * **Event Name**: an event name. Use a consistent naming pattern across your events * **Data**: extra data/attributes to include with the event. Use this data to capture business metrics (e.g., time saved, costs avoided, etc.) and/or extra data for filtering (e.g., case id) The brick automatically captures the following data/attributes: * URL: the URL where the event occurred * Email: the user's email address * Timestamp: the ISO8601 timestamp when the event occurred

Recording Customer Events to a Team Database

> Note: this brick is different than the [Send Telemetry](https://www.pixiebrix.com/marketplace/309ae2db-1ce5-429f-a952-d0359b241a7c/) brick which is used for sending telemetry to a service managed by the PixieBrix team. #### Custom Telemetry Best Practices * Use a consistent naming pattern for event names and data attributes across your events * For capturing general attributes across events, define a custom telemetry brick for your team: [#advanced-defining-a-custom-telemetry-brick](#advanced-defining-a-custom-telemetry-brick "mention") * Use event data/attributes to capture business metrics, e.g., time saved, words translated * Include a Mod Option for the Telemetry Database to keep development, testing, and production events separated * Don't capture fields that may contain personal information Record telemetry events for user-invoked actions: * Button Clicks * API calls invoked by the user (e.g., translation, search) Do NOT record events for actions that happen in excess, e.g. * Page Load Triggers * Text Selection Changes Doing so risks hitting limits outlined in PixieBrix's [data retention policy](https://docs.pixiebrix.com/developer-api/database-apis#data-retention-policy) and/or [throttle limits](https://docs.pixiebrix.com/developer-api/making-an-api-request#throttling). #### Advanced: Defining a Custom Telemetry Brick To capture different data/attributes, use the [advanced-workshop](https://docs.pixiebrix.com/developing-mods/advanced-workshop "mention") to define a custom brick. For example, here is the definition of the `@pixies/telemetry/record` brick. Note the use of the Run Bricks with `async: true` so that the mod continues to run while the telemetry is transmitted: ```yaml apiVersion: v3 kind: component metadata: id: "@pixies/telemetry/record" version: 1.0.0 name: Record Product Telemetry to DB description: Record Product telemetry to a PixieBrix team database inputSchema: $schema: "https://json-schema.org/draft/2019-09/schema#" type: object properties: pixiebrix: $ref: "https://app.pixiebrix.com/schemas/services/@pixiebrix/api" databaseId: $ref: "https://app.pixiebrix.com/schemas/database#" title: Telemetry Database eventName: title: Event Name description: "The name of the event" type: string data: title: Data type: object description: Extra data to include with the event required: - pixiebrix - databaseId - eventName - data uiSchema: "ui:order": - databaseId - eventName - data - "*" pipeline: - id: '@pixiebrix/run' # Run asynchronously to not block mod async: true config: body: !pipeline - id: '@pixiebrix/timestamp' config: {} outputKey: instant - id: '@pixiebrix/document-context' config: {} outputKey: context - id: '@pixiebrix/session' config: {} outputKey: session - id: '@pixiebrix/data/put' outputKey: record config: mergeStrategy: replace service: !var '@input.pixiebrix' key: !nunjucks '{{ @session.email }}-{{ @instant.timestamp }}' databaseId: !var "@input.databaseId" value: url: !var '@context.url' email: !var '@session.email' timestamp: !var '@instant.timestamp' event: !var "@input.eventName" data: !var "@input.data" ``` #### Common Bricks for Event Context The following bricks are the most commonly for including standard information with telemetry. See the [#advanced-defining-a-custom-telemetry-brick](#advanced-defining-a-custom-telemetry-brick "mention") section for an example of using the bricks to define a custom brick. | Brick Name | Brick ID | Description | | ------------------------ | --------------------------------- | ---------------------------------------------------------------------------------- | | Generate a Timestamp | `@pixiebrix/timestamp` | The current Unix timestamp and ISO8601 timestamp | | Context Reader | `@pixiebrix/document-context` | Information about the current page, e.g., URL | | PixieBrix Profile Reader | `@pixiebrix/profile` | Information about the user, e.g., email, group membership, organization membership | | Session Reader | `@pixiebrix/session` | Information about the page session, e.g., last navigation | | Run Metadata | `@pixiebrix/reflect/run-metadata` | Information about the current starter brick run, e.g., mod id, deployment id | ### Capturing OpenTelemetry Logs and Metrics OpenTelemetry [is a open standard for logs and metrics](https://opentelemetry.io/). To report data to an OpenTelemetry collector/backend, use the HTTP Request Brick, and provide the corresponding. For example: * `name` : event name * `timestamp` : timestamp in epoch milliseconds * `attributes`: a dictionary of attributes for the event As a best practice, use the [advanced-workshop](https://docs.pixiebrix.com/developing-mods/advanced-workshop "mention") to define a custom brick for your team that automatically includes relevant attributes (e.g., user email, etc.)