Sentry Instrument Logging

Instrument Sentry Logging

This skill adds structured Sentry logs to an application following the guidance in Instrumentation guidance.

The goal is to provide a small set of high-value log messages that make production behavior easier to understand and debug.

The log messages added by this skill should also serve as clear, repeatable, examples that users can follow when instrumenting the rest of their application.

Prerequisites

The repository should already have basic Sentry configuration.

If Sentry has not yet been configured, offer to set it up using the appropriate skills.

Steps

1. Inventory every application in the repository. Locate language/runtime manifests (composer.json, package.json, go.mod, Gemfile, pyproject.toml, Cargo.toml, …). Each manifest typically marks a separately deployed application. Produce an explicit table and treat it as the work list for the rest of this skill:

   App	Path	Language	Sentry SDK?	Logging abstraction	Status

   If the repo has more than ~2 apps, confirm scope with the user before starting: which apps to instrument now, and at what depth.

2. Establish shared conventions once, up front — before touching any app. Decide on consistent attribute namespacing (e.g. myapp.<domain>.<field>), event-name phrasing, and log levels, so logs from every language can be searched and correlated together. Record these so each per-app pass follows them. Note service boundaries that propagate trace headers (baggage / sentry-trace) — logs on both sides of such a call should share attribute names so a single trace reads coherently across languages.

3. For each application in the inventory, complete the full pass below before moving to the next, updating its Status as you go (not started → configured → instrumented → verified):

   a. Read the corresponding language-specific skill in skills and confirm Sentry logging is configured. b. Determine the app's logging abstraction (Monolog/PHP, slog/Go, Rails logger/Ruby, Pino or console/JS). If Sentry supports it, configure that integration; otherwise use Sentry's logging SDK directly. c. Identify a small number of high-value log messages, prioritizing runtime decisions, important algorithms, audit events, and context around recoverable failures. Follow Valuable log entries to instrument. d. Add structured logs following the shared conventions from Step 2 and the Instrumentation guidance. e. Verify: run the app's lint/type/test tooling if available, and confirm logs are emitted. If the toolchain isn't available locally, say so explicitly rather than implying it passed.

4. Apply a high-value log validation check. Review every added or modified log line and remove or revise any log that does not pass this check:

   Check	Question
   Production question	What concrete production question does this log answer?
   Signal	Would this still be useful if emitted hundreds or thousands of times?
   Telemetry fit	Is this better represented as a trace, metric, or Sentry error?
   Existing coverage	Is this already captured by an exception, existing log, or shared API/client wrapper?
   Structure	Are event names and attributes consistent with the shared conventions?
   Safety	Does it avoid PII, secrets, raw payloads, and unstable exception messages?
   Actionability	Would seeing this log change how someone investigates or responds?

   Prefer removing logs that merely confirm routine UI interactions, duplicate generic API failures, or record expected validation failures without adding meaningful context.

   Keep logs that explain important runtime decisions, summarize multi-step workflows, record important audit/business events, or provide context around recoverable failures.

   For each remaining log, be able to write a one-sentence justification: "This log is valuable because it helps answer <specific question>."

5. Reconcile against the inventory. Confirm every in-scope app reached verified (or was explicitly deferred). Report per-app status so partial coverage is never mistaken for full coverage.

Instrumentation guidance

When to reach for logging, vs., other types of telemetry

Logs are ideal for recording the context and decisions that explain what happened during an application's execution.

• For measuring the performance and flow of requests, use tracing.
• For unexpected critical failures, use errors.

Valuable log entries to instrument

Important runtime decisions made by your application

The decisions your application makes while serving a request are often the missing context needed to explain production behaviour.

Examples include:

• A user has a feature flag enabled, resulting in a different code path.
• Mobile users are redirected to a different experience.
• Paid and free users receive different functionality.

This information can be useful both as a standalone log entry, for example when a feature flag is evaluated, and as structured context included with later log messages.

Whether a feature or algorithm is behaving as expected

Logs are useful when a feature performs multiple steps. By recording intermediate outcomes, you can understand where a process is breaking down and why.

Here's an example from a site that allows users to import a logbook from another service:

Sentry.logger.info("Aurora import started", {
  "import.source": "aurora",
  "import.entries_received": body.ascents.length,
});

// Algorithm runs here...

Sentry.logger.info("Aurora import finished", {
  "import.source": "aurora",
  "import.entries_received": body.ascents.length,
  "import.imported": imported,
  "import.climbs_created": climbsCreated,
  "import.skipped": skipped,
  "import.skipped.missing_name": skipDetails.missingName,
  "import.skipped.unknown_grade": skipDetails.unknownGrade,
  "import.skipped.invalid_angle": skipDetails.invalidAngle,
  "import.skipped.already_imported": skipDetails.alreadyImported,
});

Key stages are logged and the final outcome summarizes the work performed, making it easier to understand where the import succeeded, failed, or produced unexpected results.

Audit and access events (creates, updates, deletes, access, permissions)

Audit logs help answer questions like "Who changed this?", "When did it happen?", and "Was this action expected?"

Log important changes to application state, such as entities being created, updated, deleted, viewed, or having permissions modified.

Use good judgment. Most applications don't need a log entry for every database operation, but they often benefit from recording security-sensitive actions and important business events.

Context surrounding errors and failures

For exceptions, you'll often be better off using errors rather than adding a log line.

Not every failure should become a Sentry issue.

Examples of failures that are often better represented as log messages include:

• Failures from non-critical, optional upstream services.
• Failures that occur in a retry loop prior to the final attempt.

For these types of error log messages, consider including:

• Retry count.
• Response status code and important non-sensitive request or response fields for external API calls.
• Runtime decisions leading up to the failure.

How to structure log messages