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.

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:

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

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.
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 nametimestamp
: timestamp in epoch millisecondsattributes
: 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.)
Last updated
Was this helpful?