MongoDB annotations
Annotations allow you to overlay event data on your time series graphs, making it easier to correlate metrics with specific events like deployments, errors, or configuration changes. For an overview of annotations, refer to Annotate visualizations.
Before you begin
- Ensure you have configured the MongoDB data source.
- Your dashboard must already be saved before creating annotations.
- Annotations display on time series, state timeline, and candlestick visualization types.
Annotation query format
Your annotation query must return at least a time field. The following table describes all recognized fields:
Note
Use the
$__timeFromand$__timeTomacros in your annotation query to limit results to the visible dashboard time range. Without these filters, the query may return all matching documents regardless of the selected time window.
Create an annotation
To create an annotation query:
- Open your dashboard and click Dashboard settings (gear icon).
- Select Annotations in the left menu.
- Click Add annotation query.
- Select your MongoDB data source.
- Enter your MongoDB query (using
aggregateorfind). - Click Save dashboard.
Annotation examples
The following examples show common annotation patterns for MongoDB.
Track deployment events
Show when deployments occurred to correlate with metric changes:
ops_db.deployments.aggregate([
{
$match: {
"deployed_at": { $gte: $__timeFrom, $lt: $__timeTo }
}
},
{
$project: {
"_id": 0,
"time": "$deployed_at",
"title": { "$concat": ["Deploy: ", "$service_name", " v", "$version"] },
"text": { "$concat": ["Environment: ", "$environment", "\nDeployed by: ", "$deployed_by"] },
"tags": "deployment"
}
}
])Track error spikes
Annotate time periods when error counts exceeded a threshold:
logs_db.errors.aggregate([
{
$match: {
"timestamp": { $gte: $__timeFrom, $lt: $__timeTo }
}
},
{
$group: {
"_id": {
"$dateTrunc": { "date": "$timestamp", "unit": "minute", "binSize": 5 }
},
"count": { "$sum": 1 },
"sample_error": { "$first": "$message" }
}
},
{
$match: { "count": { "$gt": 10 } }
},
{
$project: {
"_id": 0,
"time": "$_id",
"title": { "$concat": ["Error spike: ", { "$toString": "$count" }, " errors"] },
"text": "$sample_error",
"tags": "error,spike"
}
}
]).sort({"time": 1})Region annotations for maintenance windows
Use time and timeEnd to highlight maintenance periods:
ops_db.maintenance_windows.aggregate([
{
$match: {
"start_time": { $lte: $__timeTo },
"end_time": { $gte: $__timeFrom }
}
},
{
$project: {
"_id": 0,
"time": "$start_time",
"timeEnd": "$end_time",
"title": { "$concat": ["Maintenance: ", "$description"] },
"text": { "$concat": ["Affected services: ", "$affected_services"] },
"tags": "maintenance"
}
}
])Track configuration changes
Annotate when configuration changes were applied:
admin_db.audit_log.aggregate([
{
$match: {
"action": "config_change",
"timestamp": { $gte: $__timeFrom, $lt: $__timeTo }
}
},
{
$project: {
"_id": 0,
"time": "$timestamp",
"title": { "$concat": ["Config change: ", "$setting_name"] },
"text": { "$concat": ["Changed by: ", "$user", "\nOld value: ", "$old_value", "\nNew value: ", "$new_value"] },
"tags": "config"
}
}
]).sort({"time": 1})Next steps
- Refer to Template variables to make your annotations dynamic.
- Refer to Annotate visualizations for more annotation options.
