Analyze Runtime

Analyze an App's Runtime Behavior — Logs, Metrics, Traces, Catalog

Overview

When you need to understand what an app actually does at runtime — why a page is slow, which microflow dominates cost, what hits the database, whether an error is network or logic — the signals live in four places. This skill is the procedure for collecting them and, crucially, joining them, because the useful questions cross sources that no single tool answers alone.

When to Use This Skill

• A page/microflow is slow and you need to find where the time goes.
• You want to know which entities/queries the app actually hits, and how often.
• A server-side error shows only a generic dialog in the browser.
• You're profiling and need a flame chart, or want cost correlated with model shape.

Prerequisite: run the app with the fast local loop — see run-local. Everything below assumes mxcli run --local (add the flags noted per signal).

1. Logs — the first stop for errors

run --local writes the runtime log to <projectDir>/.mxcli/runtime.log (override --runtime-log, - disables). It carries JVM stdout/stderr and the application log — server stack traces, your microflow/nanoflow LOG output, and the DB synchronization counts at startup.

mxcli run --local -p app.mpr
tail -f .mxcli/runtime.log

Gotchas:

• Nanoflow LOG lands under the Client_Nanoflow node, not the node name you declared — a filter built around microflow node names silently drops it. LOG DEBUG from a nanoflow is dropped server-side (browser console only). See write-nanoflows.
• A spike in "Executing N database synchronization command(s)" on an unchanged model is a red flag (see the create or modify data-loss class of bug).

Turning up one subsystem: mxcli log

Everything logs at INFO by default, so the detail you need usually is not in the file at all — and raising the whole runtime to TRACE is unusable. Logging is publish/subscribe: code publishes to a named LogNode, and each node has its own level.

mxcli log list                          # every node and its level (57 on a blank 11.12 app)
mxcli log list --filter connectionbus   # narrow it — nobody remembers the exact names
mxcli log set ConnectionBus_Queries TRACE
mxcli log set ConnectionBus_Queries=TRACE Connector=DEBUG   # one admin call
mxcli log set ConnectionBus_Queries INFO                    # put it back

Levels: NONE CRITICAL ERROR WARNING INFO DEBUG TRACE.

This needs a running app (it goes through the M2EE admin API), and the change lasts as long as the process — it is a debugging knob, not project configuration.

Nodes worth knowing:

--force creates the node, permanently. Without it an unknown node is refused, which is what you want — a typo should be an error. With it the name is registered for the life of the process, so a typo becomes a real (empty) node that shows up in log list from then on. Use it only to pre-register a node that has not published yet.

Nodes appear only once something registers them, so the list is a property of this app, not of Mendix. A blank 11.12 app reports 57; adding one published OData service makes it 58. This is why log list is the first step rather than a remembered name — and why --force exists for a node that has not registered yet.

Seeing what a published OData resource is asked

OData Publish — note the space — is the node, and it exists only when the project publishes a service. At TRACE it logs the full incoming URI, which is the question $filter/$top/key-lookup bugs turn on:

mxcli log set "OData Publish" TRACE
# GET /odata/f1/Rows?$top=5&$filter=rowKey eq 'abc'

TRACE - OData Publish: Incoming request from 127.0.0.1: GET .../Rows?$top=5&$filter=rowKey eq 'abc'
DEBUG - OData Publish: Responding to client with status code 400.

ODataConsume is the client side — a different node for a different direction.

That same probe showed Mendix rejecting $filter on a property not declared Filterable, with a 400 "Property 'rowKey' is non-filterable", before the read microflow ran. So the platform does enforce the filterability you declare in expose (…); what it does not do is apply $top/$skip/$orderby for a read-microflow resource (see odata-data-sharing).

2. Metrics — throughput and database pressure

--metrics registers a Prometheus registry, served at http://127.0.0.1:<admin-port>/prometheus (loopback).

mxcli run --local -p app.mpr --metrics
curl -s http://127.0.0.1:8090/prometheus | grep -E 'connectionbus_|handler_requests|sessions_|taskqueue_'

Useful families: connectionbus_{selects,inserts,updates,deletes,transactions}_total (database pressure), handler_requests_total (throughput), sessions_*, taskqueue_* (background work). Merge any extra registry (otlp/influx/statsd) with --runtime-setting 'Metrics.Registries=[…]'.