Mod Product Telemetry

Capturing mod product engagement and error telemetry

Pre-Configured Telemetry Options

For deployed 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 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 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

• 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 and/or throttle limits.

Advanced: Defining a Custom Telemetry Brick

To capture different data/attributes, use the Advanced: Workshop 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:

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 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.

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 to define a custom brick for your team that automatically includes relevant attributes (e.g., user email, etc.)