Get backend exceptions into Issues ¶

The Nais APM Issues tab groups your service's backend exceptions from Loki. How good that grouping is depends entirely on how the exception reaches Loki — and in particular on which of the two log-ingest paths your app uses.

Most nais apps ship logs the default way — stdout → fluentbit → Loki — and deliberately do not enable OpenTelemetry log export (they keep control of stdout, often to multi-ship some logs elsewhere). So this guide leads with getting the best possible Issues on that default path, then covers the OpenTelemetry option that unlocks the richest shape.

Why the log shape matters ¶

Nais APM reads three shapes of backend exception from Loki, best to worst:

Which path do your logs take? ¶

Your ceiling is set by how your logs get into Loki, not by your logging code alone:

So on the default stdout path, shape B is the ceiling: an exception_type field inside your JSON body is never promoted to a label, and shape A selects on exception_type != "" as structured metadata — so it can only match logs that arrived over OpenTelemetry.

Get the best Issues over stdout (shape B) ¶

This is the path most teams are on. Three habits get you the tightest, most useful backend Issues that Loki can give you without OpenTelemetry.

1. Log structured JSON ¶

Shape B is parsed with | json, so your stdout lines must be JSON with a message (or msg) field and an error-class level. Use your framework's JSON encoder:

2. Keep the error message a stable literal ¶

Shape B groups by the message. If you interpolate a case id, URL, or count into the message, every occurrence becomes its own group and one error fragments into dozens of near-duplicate Issues. Keep the message a fixed string and put the variable data in separate JSON fields:

JVM (Kotlin)

// BAD — the id in the message fragments grouping
log.error("Failed to fetch behandling $behandlingId")
// GOOD — stable message; id as a structured field (StructuredArguments.kv)
log.error("Failed to fetch behandling", kv("behandlingId", behandlingId), e)

Node.js (Pino)

// BAD — id in the message fragments grouping
logger.error(`Failed to fetch behandling ${behandlingId}`);
// GOOD — stable message, id as a field, error as an object
logger.error({ behandlingId, err }, "Failed to fetch behandling");

3. Log the exception as an object ¶

Pass the throwable / Error object to the logger — never a string you built from it. On the stdout path this puts the exception's stack trace into the JSON line, which the Issues tab's occurrence drawer reads from a top-level stack_trace or stack field:

Reach shape A with OpenTelemetry log export (one option) ¶

If you already use OpenTelemetry logs, or you're willing to dual-ship, exporting logs over OTLP is the only way to reach shape A. The collector sends each log record to Loki's OTLP endpoint, which stores the semantic-convention exception attributes as structured metadata:

The Issues tab then groups on exception_type + exception_message, with the class and full stack trace in each Issue.

JVM (Spring Boot and Ktor) ¶

Enable the Java agent's log bridge and log with the throwable. In nais.yaml:

spec:
  observability:
    autoInstrumentation:
      enabled: true
      runtime: java
  env:
    - name: OTEL_LOGS_EXPORTER
      value: otlp

The auto-instrumentation Java agent bridges Logback/Log4j2 to OTel logs; when a log event carries a Throwable, the appender attaches exception.type/message/stacktrace automatically. Spring Boot and Ktor both use SLF4J + Logback by default, so logging the throwable is all you need — no logback.xml change or extra dependency.

Log what escapes your handlers once, with the throwable. Spring — a @RestControllerAdvice:

@RestControllerAdvice
class GlobalExceptionHandler {
    private val log = LoggerFactory.getLogger(javaClass)

    @ExceptionHandler(Exception::class)
    fun handle(e: Exception): ResponseEntity<String> {
        log.error("Unhandled exception", e)
        return ResponseEntity.internalServerError().body("Internal error")
    }
}

Ktor — the StatusPages plugin:

install(StatusPages) {
    exception<Throwable> { call, cause ->
        call.application.log.error("Unhandled exception", cause)
        call.respondText("Internal error", status = HttpStatusCode.InternalServerError)
    }
}

Node.js (Express / Next.js) ¶

runtime: nodejs bundles the Winston and Pino instrumentations, whose log-sending appenders map a logged Error onto exception.* for you:

spec:
  observability:
    autoInstrumentation:
      enabled: true
      runtime: nodejs
  env:
    - name: OTEL_LOGS_EXPORTER
      value: otlp

Log the Error object so the appender can read its name, message, and stack:

// Pino: the Error under `err` → exception.type/message/stacktrace
logger.error({ behandlingId, err }, "Failed to fetch behandling");

// Winston: the Error passed alongside the message
// logger.error("Failed to fetch behandling", { behandlingId, err });

The four-argument Express error-handling middleware (err, req, res, next), registered after your routes, is the natural place to catch what escapes a route (the same appender applies to Next.js route handlers and API routes):

app.use((err, req, res, next) => {
    logger.error({ err }, "Unhandled error");
    res.status(500).send("Internal Server Error");
});

Field mapping ¶

What the app produces on the OTLP path, and how it lands in the Issues tab:

The Issues tab selects shape A with, in effect:

sum by (exception_type, exception_message) (
  count_over_time({service_name="<app>", service_namespace="<team>"} | exception_type != "" [$__range])
)

Go ¶

Go is a smaller slice of nais apps and largely the platform team's domain, so briefly: Go uses runtime: sdk — no agent — so your app wires OpenTelemetry itself. For the stdout path the same shape-B advice applies (structured JSON, stable message, error as a field). For shape A you build a LoggerProvider with the OTLP log exporter and the otelslog bridge, then set the exception.* attributes yourself — the bridge does not map errors, and because a Go error carries no stack, exception.stacktrace is manual and weaker than the JVM's:

slog.ErrorContext(ctx, "failed to fetch behandling",
    slog.String("behandlingId", behandlingId),
    slog.String("exception.type", fmt.Sprintf("%T", err)),
    slog.String("exception.message", err.Error()),
)

Log the exception, not a bare message ¶

Whichever path you're on, this is the single biggest reason backend Issues come out thin: hand the logging framework the throwable/error object, not a string you built from it, and keep the message stable.

Log the object, never a pre-formatted string ¶

JVM (Kotlin)

// BAD  — class and stack lost inside a string
log.warn("Failed to fetch behandling $behandlingId: ${e.message}")
// GOOD — stable message, throwable as the last arg, id as a field
log.warn("Failed to fetch behandling", kv("behandlingId", behandlingId), e)

Node.js (Pino)

// BAD
logger.warn(`Failed to fetch behandling ${behandlingId}: ${err.message}`);
// GOOD
logger.warn({ behandlingId, err }, "Failed to fetch behandling");

Don't log self-healing retries at error or warn ¶

A message that logs on every retry and then recovers is still counted as an Issue — often a top Issue — even though nothing was actually broken. Log retries at info/debug, and only escalate to error when the final attempt fails. For example, a client calling the Oppgave API:

async function createOppgave(payload, attempts = 3) {
    for (let i = 1; i <= attempts; i++) {
        try {
            return await oppgaveClient.create(payload);
        } catch (err) {
            if (i === attempts) {
                // only the terminal failure becomes an Issue
                logger.error({ err, saksId: payload.saksId, attempts }, "Failed to create oppgave");
                throw err;
            }
            // transient, self-healing — not an Issue
            logger.debug({ saksId: payload.saksId, attempt: i }, "Oppgave call failed, retrying");
        }
    }
}

Put context in fields, not in the message ¶

Add identifiers and status as structured fields (saksId, behandlingId, journalpostId, oppgaveId, status) rather than concatenating them into the message. They become queryable, and — because grouping is on the message — keeping variable data out of the message keeps one error from fragmenting into dozens of near-duplicate Issues.

Verify it works ¶

If you're on stdout and one error fragments into near-duplicate Issues, your message is carrying variable data — revisit step 2.

Known limitations and cost ¶

Related ¶