LogisterDocumentationCFML integration
Documentation / CFML

Integrate a Lucee or ColdFusion site with Logister.

CFML apps can send events directly to Logister with cfhttp. The best path is a small LogisterClient.cfc wrapper plus Application.cfc.onError() for uncaught exceptions.

Before you start

Create the project with the CFML integration type.

What you needWhy it matters
Project API tokenAuthenticates each request to Logister
Logister host URLUsed to build the ingest and check-in endpoints
Access to Application.cfcLets you hook uncaught exceptions centrally

What you get

Use CFML events to make Lucee and ColdFusion failures visible in the same Logister workflow.

NeedWhat appears in Logister
Catch uncaught CFML exceptionsInbox issues with CFML exception summary, detail text, and template frames when you include tagContext, tag_context, stacktrace, or stack_trace.
Understand the request around the errorRequest details from CGI context such as script name, method, and query string.
Add performance visibility graduallyTransaction events for requests or CFC methods, span events for request load waterfalls, and metric events for query, cache, or outbound HTTP timings.
Watch scheduled tasksCheck-ins for scheduled tasks and cron-style jobs on the monitor page.
Keep custom logs close to errorsLog events with request, release, or user metadata in the activity feed and related-log tab.

Setup flow

Recommended installation path

  1. Create the project, choose CFML, and generate an API key.
  2. Add a small LogisterClient.cfc wrapper around cfhttp.
  3. Hook uncaught exceptions into Application.cfc.onError().
  4. Send request timings as transaction events, request load pieces as span events, and query timings as metric events.

Tip

Start with uncaught exception capture, then add transactions, spans, metrics, logs, and check-ins one by one as you verify each payload shape.

Start with

Send a structured error event.

shell
POST /api/v1/ingest_events

Logister accepts the canonical lowercase event envelope and common CFML/Lucee uppercase variants such as EVENT. Nested event keys are normalized too, so eventType, event_type, traceId, and trace_id all map to the expected fields. The endpoint accepts 1,200 requests per minute per API token by default and returns 429 Too Many Requests with retry headers when that limit is exceeded.

cfml
application.logister.sendEvent(
  eventType = "error",
  level = "error",
  message = exception.message ?: "Unhandled CFML exception",
  context = {
    exception = {
      type = exception.type ?: "Exception",
      detail = exception.detail ?: "",
      tagContext = exception.tagContext ?: [],
      stacktrace = exception.stackTrace ?: ""
    }
  }
);
Verification
request accepted
error visible in project inbox
stack frames rendered from tagContext or stacktrace

Error handling

Capture uncaught exceptions with Application.cfc.onError().

  • exception.type and exception.message drive the exception summary
  • exception.detail improves the ColdFusion exception panel
  • exception.tagContext or exception.tag_context populates template frames
  • exception.stacktrace or exception.stack_trace can also render stack frames when tag context is not available
  • context.cgi.script_name and related CGI fields improve request context
cfml
public void function onError(any exception, string eventName) {
  application.logister.sendEvent(
    eventType = "error",
    level = "error",
    message = exception.message ?: "Unhandled exception",
    context = {
      exception = {
        type = exception.type ?: "Exception",
        detail = exception.detail ?: "",
        tagContext = exception.tagContext ?: [],
        stacktrace = exception.stackTrace ?: ""
      },
      cgi = {
        script_name = cgi.script_name ?: "",
        request_method = cgi.request_method ?: "",
        query_string = cgi.query_string ?: ""
      }
    }
  );
}

Important

If you omit both tag context and stacktrace fields, Logister can still store the event, but the CFML error view loses the template-frame detail that makes debugging much easier.

Event types

Use structured event types consistently.

Event typeTypical CFML use
errorUnhandled exceptions from Application.cfc.onError() or manual rescue paths
transactionRequest timing, CFC method timing, remote call latency
spanRoot request spans plus child spans for database, render, cache, HTTP, queue, or internal work
metricdb.query, cache timings, outbound HTTP timings, queue depth, business counters
logApplication logs with request or release metadata
check_inScheduled jobs, task runners, cron-style heartbeats
Error
Start here so you can confirm payload authentication and exception rendering.
Transaction
Add request timings next so the performance view becomes useful quickly.
Span
Add root and child spans when you want request load waterfall charts.
Metric
Layer in db.query and other timings for deeper latency analysis.
Check-in
Finish with scheduled jobs and cron heartbeats for monitor coverage.

Useful examples

Send one focused event for each CFML workflow you care about.

Request transaction and root span

cfml
traceId = createUUID();
requestId = traceId;
rootSpanId = replace(createUUID(), "-", "", "all");
requestDurationMs = getTickCount() - request.startedAt;

application.logister.sendEvent(
  eventType = "transaction",
  level = "info",
  message = cgi.request_method & " " & cgi.script_name,
  transactionName = cgi.request_method & " " & cgi.script_name,
  durationMs = requestDurationMs,
  traceId = traceId,
  requestId = requestId,
  context = { service = "cfml-web", route = cgi.script_name }
);

application.logister.sendEvent(
  eventType = "span",
  name = cgi.request_method & " " & cgi.script_name,
  kind = "server",
  traceId = traceId,
  spanId = rootSpanId,
  durationMs = requestDurationMs,
  context = { route = cgi.script_name, service = "cfml-web" }
);

Database metric and scheduled-task check-in

cfml
application.logister.sendEvent(
  eventType = "metric",
  level = "info",
  message = "db.query",
  durationMs = queryDurationMs,
  context = {
    value = queryDurationMs,
    unit = "ms",
    query = "Order lookup",
    service = "cfml-web"
  }
);

application.logister.sendEvent(
  eventType = "check_in",
  level = "info",
  message = "nightly-reconcile",
  checkInSlug = "nightly-reconcile",
  checkInStatus = "ok",
  expectedIntervalSeconds = 3600,
  durationMs = reconcileDurationMs,
  context = { service = "cfml-worker" }
);

Use transactions for total work, spans for waterfalls, metrics for numeric series, logs for narrative context, and check-ins for scheduled tasks. Keep keys stable and low-cardinality so Insights filters stay useful.

More detail

Need more reference material?

The static docs now carry the CFML setup flow directly. For lower-level payload details, pair this page with the HTTP API guide and Swagger/OpenAPI reference so you can verify exact request shapes and authentication headers.