Skip to content
Skills Library
DevOps & cloud · Building & coding

intercom-observability

/intercom-observability

Use when you need production monitoring for an Intercom integration — instrumenting API calls with metrics and traces, standing up dashboards, or wiring alerts for error rate, latency, and rate-limit health. Set up observability for Intercom integrations with Prometheus metrics, OpenTelemetry traces, structured logging, and alert rules. Trigger with phrases like "intercom monitoring", "intercom metrics", "intercom observability", "monitor intercom", "intercom alerts", "intercom tracing".

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when you need production monitoring for an Intercom integration — instrumenting API calls with metrics and traces, standing up dashboards, or wiring alerts for error rate, latency, and rate-limit health. Set up observability for Intercom integrations with Prometheus metrics, OpenTelemetry traces, structured logging, and alert rules. Trigger with phrases like "intercom monitoring", "intercom metrics", "intercom observability", "monitor intercom", "intercom alerts", "intercom tracing".

Triggers from the description

intercom monitoringintercom metricsintercom observabilitymonitor intercomintercom alertsintercom tracing
Original author description

Use when you need production monitoring for an Intercom integration — instrumenting API calls with metrics and traces, standing up dashboards, or wiring alerts for error rate, latency, and rate-limit health. Set up observability for Intercom integrations with Prometheus metrics, OpenTelemetry traces, structured logging, and alert rules. Trigger with phrases like "intercom monitoring", "intercom metrics", "intercom observability", "monitor intercom", "intercom alerts", "intercom tracing".

How it works

  1. Overview
  2. Prerequisites
  3. Instructions
  4. Output
  5. Error Handling
  6. Examples
  7. Resources
  8. Next Steps
Original SKILL.md headings · 139 lines, 738 words
SKILL.md preview
---
name: intercom-observability
description: |
  Use when you need production monitoring for an Intercom integration — instrumenting
  API calls with metrics and traces, standing up dashboards, or wiring alerts for
  error rate, latency, and rate-limit health.
  Set up observability for Intercom integrations with Prometheus metrics,
  OpenTelemetry traces, structured logging, and alert rules.
  Trigger with phrases like "intercom monitoring", "intercom metrics",
  "intercom observability", "monitor intercom", "intercom alerts", "intercom tracing".
allowed-tools: Read, Write, Edit
version: 1.6.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- support
- messaging
- intercom
compatibility: Designed for Claude Code
---
# Intercom Observability

## Overview

Comprehensive observability for Intercom integrations covering Prometheus metrics,
OpenTelemetry traces, structured logging, and alert rules for error rates, latency,
and rate-limit usage. Read this page for the workflow and shape of each layer, then
drill into [`references/implementation.md`](references/implementation.md) for the full,
copy-pasteable code and [`references/examples.md`](references/examples.md) for
end-to-end worked scenarios.

## Prerequisites

- Prometheus or compatible metrics backend
- OpenTelemetry SDK (optional, for tracing)
- Pino or similar structured logger
- Grafana or alerting system

## Instructions

Build the six observability layers in order. Each step below is the summary and the
essential skeleton — the complete implementation for every step lives in
[`references/implementation.md`](references/implementation.md).

### Step 1: Prometheus metrics

Define five instruments on a shared `Registry`: a request counter, a duration
histogram, an error counter, a rate-limit gauge, and a webhook counter. Label by
`endpoint`/`method`/`status` (never by unbounded IDs — see Error Handling).

```typescript
import { Registry, Counter, Histogram, Gauge } from "prom-client";
const registry = new Registry();
const intercomRequests = new Counter({
  name: "intercom_api_requests_total",
  help: "Total Intercom API requests",
  labelNames: ["endpoint", "method", "status"] as const,
  registers: [registry],
});
// + duration Histogram, error Counter, rate-limit Gauge, webhook Counter
```

Full metric set → [references/implementation.md](references/implementation.md), Step 1.

### Step 2: Instrumented client wrapper

Wrap `IntercomClient` in a `Proxy` that times every service method, increments the
success/error counters, records error/status codes on `IntercomError`, and zeros the
rate-limit gauge on a 429 — so instrumentation is automatic for all endpoints.
Full proxy → [references/implementation.md](references/implementation.md), Step 2.

### Step 3: Structured logging

Configure Pino with a `contact` serializer that emits only `id`/`role` and **never**
logs email, name, or phone. Add `logIntercomOp` and `logWebhook` helpers for
consistent operation/webhook log lines.
Full logger → [references/implementation.md](references/implementation.md), Step 3.

### Step 4: OpenTelemetry tracing

Wrap calls in `tracedIntercomCall`, which opens a per-operation `intercom.*` span, sets
OK/ERROR status, records exceptions, and attaches `status_code`/`error_code`/`request_id`
attributes on Intercom errors.
Full tracer → [references/implementation.md](references/implementation.md), Step 4.

### Step 5: Alert rules

Ship the Prometheus rule group with five alerts: high error rate (>5%), high P95
latency (>3s), low rate limit (<1000), auth failures (401s), and webhook failures.
Full YAML → [references/implementation.md](references/implementation.md), Step 5.

### Step 6: Metrics endpoint

Expose the registry on `GET /metrics` for Prometheus to scrape.
Full route → [references/implementation.md](references/implementation.md), Step 6.

## Output

Applying this skill produces:

- **Instrumented client** — an `IntercomClient` proxy that emits metrics on every call, with zero per-call changes to existing code.
- **Metrics** — `intercom_api_requests_total`, `intercom_api_request_duration_seconds`, `intercom_api_errors_total`, `intercom_rate_limit_remaining`, `intercom_webhooks_processed_total`, scraped at `GET /metrics`.
- **Traces** — one per-operation `intercom.*` span per call, with Intercom error attributes on failures.
- **Structured logs** — PII-redacted JSON operation and webhook log lines.
- **Alerts** — a Prometheus rule group covering error rate, latency, rate limit, auth, and webhooks.

### Key metrics summary

| Metric | Type | Alert Threshold |
|--------|------|----------------|
| `intercom_api_requests_total` | Counter | N/A (baseline) |
| `intercom_api_request_duration_seconds` | Histogram | P95 > 3s |
| `intercom_api_errors_total` | Counter | > 5% error rate |
| `intercom_rate_limit_remaining` | Gauge | < 1000 |
| `intercom_webhooks_processed_total` | Counter | Failed > 10% |

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| High cardinality | Too many unique labels | Use endpoint groups, not IDs |
| Missing metrics | Uninstrumented calls | Wrap client with proxy |
| Alert storms | Wrong thresholds | Tune based on baseline data |
| Log volume too high | Debug logging in prod | Set LOG_LEVEL=info |

## Examples

The following scenarios are covered in full in
[`references/examples.md`](references/examples.md):

- **Contact lookup end-to-end** — one `contacts.find` call producing a counter increment, a histogram sample, a span, and a PII-redacted log line.
- **Rate-limit (429) event** — how the proxy zeros the rate-limit gauge and which alerts fire.
- **Webhook success/failure accounting** — counting processed vs. failed webhooks per topic.
- **Scraping `/metrics`** — the raw Prometheus exposition and how it feeds Grafana and the alert rules.

Minimal end-to-end skeleton:

```typescript
const client = instrumentedClient(new IntercomClient({ token: process.env.INTERCOM_ACCESS_TOKEN! }));
const contact = await tracedIntercomCall(
  "contacts.find",
  { "intercom.contact_id": contactId },
  () => client.contacts.find({ contactId })
);
```

## Resources

- [full implementation walkthrough](references/implementation.md) — every step's complete code
- [worked examples](references/examples.md) — end-to-end scenarios and observed output
- [Prometheus Best Practices](https://prometheus.io/docs/practices/naming/)
- [OpenTelemetry Node.js](https://opentelemetry.io/docs/languages/js/)
- [Pino Logger](https://getpino.io/)

## Next Steps

For incident response once these signals are firing, see the `intercom-incident-runbook`
skill, which turns these alerts into a triage-and-mitigation procedure.
Files in this package (3)
  • SKILL.md 7 KB
  • references/examples.md 3 KB
  • references/implementation.md 8 KB

Versions

The database has no other skills named intercom-observability.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 6b1cd96c5318 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100shopify-observability
    Set up observability for Shopify app integrations with query cost tracking, rate limit monitoring, webhook delivery metrics, and structured logging. Use when instrumenting a Shopify app for production monitoring, setting up Prometheus metrics for API health, or configuring…
  • 100intercom-ci-integration
    Configure CI/CD pipelines for Intercom integrations with GitHub Actions. Use when setting up automated testing, configuring CI with Intercom secrets, or integrating Intercom API tests into your build process. Trigger with phrases like "intercom CI", "intercom GitHub Actions",…
  • 100perplexity-observability
    Set up comprehensive observability for Perplexity integrations with metrics, traces, and alerts. Use when implementing monitoring for Perplexity operations, setting up dashboards, or configuring alerting for Perplexity integration health. Trigger with phrases like "perplexity…
  • 100exa-observability
    Set up comprehensive observability for Exa integrations with metrics, traces, and alerts. Use when implementing monitoring for Exa operations, setting up dashboards, or configuring alerting for Exa integration health. Trigger with phrases like "exa monitoring", "exa metrics",…
  • 100monitoring-observability
    OpenTelemetry, structured logging, distributed tracing, alerting, and dashboards. Use when instrumenting services, designing logs/traces/metrics, defining SLOs and alerts, or debugging production behavior from telemetry.
  • 91observability-engineering
    Use this skill when setting up monitoring, adding observability, or instrumenting with OpenTelemetry — also when creating SLOs and error budgets, designing alerts, aggregating logs, tracing distributed requests, or building Grafana/Prometheus dashboards. Implements…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.