CFML Integration Docs

Guide overview

Use direct ingest calls when your app runs on Lucee or Adobe ColdFusion.

The CFML path keeps things explicit: send structured payloads with cfhttp, centralize exception capture in Application.cfc, and map your request timings to Logister event types.

After reading this guide, you will know:

How to create a CFML project and generate the API token.
How to send your first structured error payload.
How to wire uncaught exceptions through Application.cfc.onError().
How to map transactions, metrics, logs, and check-ins into Logister.

Before you start

Create the project with the `CFML` integration type.

In Logister, choose CFML for the project integration type. That makes the project settings page show CFML-specific setup guidance and links back to this public guide.

What you need	Why it matters
Project API token	Authenticates each request to Logister
Logister host URL	Used to build the ingest and check-in endpoints
Access to `Application.cfc`	Lets you hook uncaught exceptions centrally

Setup flow

Recommended installation path

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

Tip

The cleanest rollout is to start with uncaught exception capture, then add transactions, metrics, logs, and check-ins one by one as you verify each payload shape.

Start with

Send a structured error event

POST the error event to Logister

shell

POST /api/v1/ingest_events

Example payload sender

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 ?: []
    }
  }
);

That first payload is usually enough to confirm authentication, endpoint wiring, and the CFML-specific error presentation in Logister.

Verification

First verification target
request accepted
error visible in project inbox
stack frames rendered from tagContext

Error handling

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

The CFML error view in Logister is optimized for structured exception data. Include fields like exception.type, exception.detail, exception.tagContext, and context.cgi for the best result.

Recommended payload fields

exception.type and exception.message drive the exception summary
exception.detail improves the ColdFusion exception panel
exception.tagContext populates template frames
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 ?: []
      },
      cgi = {
        script_name = cgi.script_name ?: "",
        request_method = cgi.request_method ?: "",
        query_string = cgi.query_string ?: ""
      }
    }
  );
}

Important

If you omit tagContext, Logister can still store the event, but the CFML error view will lose the template-frame detail that makes debugging much easier.

Event types

Use structured event types consistently

transaction for request timings and remote CFC method timings
metric for db.query, HTTP client timings, cache timings, and queue latency
log for structured application logs with correlation fields
check_in or /api/v1/check_ins for scheduled jobs

Event type	Typical CFML use
`transaction`	Request timing, CFC method timing, remote call latency
`metric`	`db.query`, cache timings, outbound HTTP timings
`log`	Application logs with request or release metadata
`check_in`	Scheduled jobs, task runners, cron-style heartbeats

Suggested rollout order

Error: Start here so you can confirm payload authentication and exception rendering.
Transaction: Add request timings next so the performance view becomes useful quickly.
Metric: Layer in db.query and other timings for deeper latency analysis.
Check-in: Finish with scheduled jobs and cron heartbeats for monitor coverage.

More detail

Need more reference material?

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

Next step

Once the first error event lands correctly, the next best additions are request transactions and db.query metrics so the performance pages become useful right away.

Integrate a Lucee or ColdFusion site with Logister.