Observability and Integrations

Overview

Bloqr Systems helps you see what the filter blocks, why it blocks it, and how the system behaves over time. This page gives you a starter-kit setup for exporting metrics, shipping logs, and wiring alerts into your existing tools.

Use this guide as a template you can adapt to your own stack. The examples below are generic by design so you can replace endpoints, tokens, and field names with the conventions used in your environment.

What you can observe

Recommended rollout

Metrics and logs

You should expose the same event in both metrics and logs so you can move from trend analysis to root cause analysis without changing tools. Metrics answer how often and how fast; logs answer what happened for a specific request.

A practical baseline includes counters for allowed and blocked requests, a histogram for request latency, and a log record for each decision. Keep labels stable and low-cardinality so your dashboards remain fast and readable.

Example event payload

{
  "timestamp": "2026-10-26T12:30:45Z",
  "request_id": "req_01JZ8Y7Q9K6V4F2B3A8M",
  "service": "assistant-gateway",
  "policy": "default-ai-filter",
  "action": "blocked",
  "reason": "sensitive-data-detected",
  "latency_ms": 18
}

Suggested metric names

Sentry integration

Sentry works well when you want exception visibility for integration failures, SDK errors, or unexpected response handling. A common pattern is to capture operational errors only, while keeping policy decisions in metrics and logs.

Use Sentry for questions like these:

• Did the exporter fail to deliver an event?
• Did an upstream integration return an invalid payload?
• Did a client-side hook throw during enrichment?

import * as Sentry from "@sentry/node";

Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
environment: "production",
});

export function reportBloqrError(error, context) {
Sentry.withScope((scope) => {
  scope.setTag("integration", "bloqr-observability");
  scope.setContext("bloqr", context);
  Sentry.captureException(error);
});
}

import sentry_sdk

sentry_sdk.init(
  dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
  environment="production",
)

def report_bloqr_error(error, context):
  with sentry_sdk.push_scope() as scope:
      scope.set_tag("integration", "bloqr-observability")
      scope.set_context("bloqr", context)
      sentry_sdk.capture_exception(error)

curl -X POST https://api.example.com/integrations/sentry/events \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
  "service": "assistant-gateway",
  "level": "error",
  "message": "Exporter timeout",
  "request_id": "req_01JZ8Y7Q9K6V4F2B3A8M"
}'

Prometheus support

Prometheus is a strong fit when you need dashboards, alert rules, and long-term operational trends. Export counters and histograms from your service, then scrape them through your existing Prometheus setup.

Keep your labels focused. Good labels are things like environment, policy, and action. Avoid request-specific values in labels because they can explode cardinality and slow down queries.

Example Prometheus exposition

# HELP bloqr_requests_total Total requests evaluated by Bloqr AI
# TYPE bloqr_requests_total counter
bloqr_requests_total{environment="production",policy="default-ai-filter",action="allowed"} 18432
bloqr_requests_total{environment="production",policy="default-ai-filter",action="blocked"} 982

# HELP bloqr_request_latency_ms Evaluation latency in milliseconds
# TYPE bloqr_request_latency_ms histogram
bloqr_request_latency_ms_bucket{le="5"} 1200
bloqr_request_latency_ms_bucket{le="10"} 8600
bloqr_request_latency_ms_bucket{le="25"} 18100
bloqr_request_latency_ms_sum 204312
bloqr_request_latency_ms_count 19414

Example scrape configuration

scrape_configs:
  - job_name: "bloqr-ai"
    metrics_path: /metrics
    static_configs:
      - targets:
          - "observability-service.example.internal:9100"

Custom observability providers

If you already use Datadog, OpenTelemetry, Splunk, or another internal platform, you can forward the same core signals to your preferred destination. The pattern stays the same: normalize the event, enrich it once, and fan it out to each destination.

Use a custom provider when you need one of these:

• A vendor-specific ingestion API
• Internal routing rules for compliance
• Custom field mapping for existing dashboards
• Regional storage or retention controls

Provider comparison

Implementation examples

import express from "express";

const app = express();

app.post("/bloqr/events", express.json(), (req, res) => {
const event = {
request_id: req.body.request_id,
policy: req.body.policy,
action: req.body.action,
reason: req.body.reason,
timestamp: new Date().toISOString(),
};

console.log(JSON.stringify(event));
res.status(202).json({ accepted: true });
});

app.listen(3000, () => {
console.log("Observability endpoint listening on port 3000");
});

from flask import Flask, request, jsonify
from datetime import datetime

app = Flask(__name__)

@app.post("/bloqr/events")
def bloqr_events():
payload = request.get_json()
event = {
    "request_id": payload.get("request_id"),
    "policy": payload.get("policy"),
    "action": payload.get("action"),
    "reason": payload.get("reason"),
    "timestamp": datetime.utcnow().isoformat() + "Z",
}

print(event)
return jsonify({"accepted": True}), 202

if __name__ == "__main__":
app.run(port=3000)

curl -X POST https://your-webhook-url.com/webhook \
-H "Content-Type: application/json" \
-d '{
"source": "bloqr-ai",
"event": "request.blocked",
"request_id": "req_01JZ8Y7Q9K6V4F2B3A8M",
"policy": "default-ai-filter"
}'

Security and operational guidance

Good operating practices

• Use a stable request_id across logs, metrics, and alerts.
• Redact user input before export when the content may contain sensitive data.
• Add sampling for high-volume allow events if your dashboard does not need every record.
• Keep dashboards simple so operators can answer questions quickly.
• Test alert routing in a staging environment before enabling production paging.

Advanced questions

Next steps

Start with a single metrics stream, then add logs and alerts once the numbers look stable. After that, connect your preferred provider and validate that blocked requests appear in the tools your team already uses.