Learn Backstage - Observability & Tech Insights

#Introduction

Episode 19 brought Backstage to large scale; episode 20 makes sure you can see what's happening inside. A Backstage serving thousands of engineers is a complex system — catalog, scaffolder, auth, and dozens of plugins all interconnected. Without observability, failure feels like guesswork. Here you'll learn four observability signals: structured logs, OpenTelemetry metrics and traces, Prometheus collection, and analytics events — then close with Tech Insights for automatically monitoring entity health.

#Observability Signals in Backstage

There are four complementary signals, each answering a different question:

#Structured Logging

Backstage uses a winston-based logger. For production, logs must be in a structured format — JSON — so they're easy to search and group in Loki, Elasticsearch, or CloudWatch. The key is field consistency: level, service, plugin, timestamp, and message.

LOG_FORMAT=json node packages/backend

Structured logs enable fast filtering: show only errors from the scaffolder plugin, or find all requests from a particular user. Without structure, operations at large scale drown in text that can't be queried.

#OpenTelemetry: Metrics and Traces

OpenTelemetry has become the standard for measuring Backstage performance. With the OpenTelemetry SDK, the backend can export metrics and traces to a collector via the OTLP protocol. The export direction is controlled through standard OpenTelemetry environment variables:

OTEL_SERVICE_NAME=backstage
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.internal:4318

Common uses:

• Traces — follow one request's journey from the Ingress to the database query, including long-running scaffolder tasks.
• Metrics — monitor request rate, error rate, and p95 duration per plugin.

Traces are especially helpful for finding slow spots: whether time is lost in a plugin, a catalog query, or a call to an external service.

#Prometheus Collection

Prometheus works by pulling metrics from a specific endpoint. The backend can expose a metrics endpoint to be scraped:

scrape_configs:
  - job_name: backstage
    metrics_path: /metrics
    static_configs:
      - targets:
          - backstage-backend.internal:7007

With data in Prometheus, create alerts for dangerous conditions — for example a sharply rising error rate or a growing scaffolder task queue — so the team can act before users complain.

#Analytics Events

Analytics answers user experience questions: how many people used the scaffolder this month, which pages are visited most, or which templates are used most often. Backstage provides an Analytics API, and events are sent to a backend analytics service (for example GA, Mixpanel, Segment, or PostHog) through an analytics module:

import { useAnalytics } from '@backstage/core-plugin-api';
 
const analytics = useAnalytics();
analytics.captureEvent('create', { entityRef: 'service:acme/payment-api' });

Analytics events become the material for evaluating adoption — whether the golden path is really being used — and will be used again in episode 22 to measure DORA metrics.

#Tech Insights and Scoring Cards

Tech Insights is a Backstage plugin for automatically monitoring the quality and health of entities in the catalog. The concept: collect facts about entities, check them against rules, then assign scores. Its four main components:

#Fact Collectors

Fact collectors pull data from various sources — the catalog, external systems, or code — and store it as facts per entity. Facts are defined via FactRetriever:

export const techdocsFactRetriever: FactRetriever = {
  id: 'techdocs-fact-retriever',
  version: '0.1.0',
  entityFilter: [{ kind: 'component' }],
  handler: async (ctx) => {
    const entities = await ctx.entityClient.listEntities({ filter: ctx.entityFilter });
    return entities.map((entity) => ({
      entity: { namespace: 'default', kind: 'Component', name: entity.metadata.name },
      facts: { hasTechDocs: entity.metadata.annotations?.['backstage.io/techdocs-ref'] !== undefined },
    }));
  },
};

Facts are stored and updated periodically, becoming the raw material for checks.

#Checks

A check is a boolean rule that evaluates an entity from available facts. Checks are created with createCheck. Here's an example check ensuring every component has documentation:

export const techdocsCheck = createCheck({
  id: 'techdocs-check',
  type: 'boolean',
  name: 'Memiliki TechDocs',
  description: 'Komponen seharusnya memiliki dokumentasi TechDocs',
  factIds: ['techdocs-fact-retriever'],
  rule: async (facts) => facts.hasTechDocs === true,
});

Checks can be assembled for various best practices: has an owner, has a description, uses a golden path template, or no longer uses deprecated versions.

#Scoring and Health Checks over Entities

Several checks are combined into a scoring that describes an entity's overall health — for example a compliance score from 0 to 100. Health checks like these are very useful for:

• Best practice — making sure entities follow internal standards, such as ownership and documentation.
• Deprecation — detecting entities using old versions or abandoned technologies.
• Maturity — measuring a service's maturity before it meets production standards.

#Conclusion

In this episode 20, you understood Backstage observability through four signals: structured logging for finding events, OpenTelemetry for metrics and traces, Prometheus for collection and alerting, and analytics events for understanding user behavior. You also learned Tech Insights: fact collectors, checks, scoring, and health checks for keeping entity quality.

The key takeaways:

• Four signals complement each other — logs for detail, metrics for quantity, traces for journeys, analytics for users.
• Logs must be structured — JSON makes searching and grouping possible.
• Tech Insights is continuous assessment — facts, checks, and scores make entity quality measurable.
• Start with what's actionable — one good alert is more useful than a dashboard full of never-read data.

In episode 21, you take all this knowledge into a real environment: production deployment & adoption. We'll wrap Backstage into a Docker image, deploy it with a Helm chart on Kubernetes, set up a CI/CD pipeline, backup and restore, a weekly upgrade strategy, and an adoption playbook for the teams in your organization.