Trails is your organization’s audit log. Each call made to an EZGH Cloud public API in your
organization, and each change the platform makes to your resources, is recorded as an event:
who acted, from where, with which credential, on which resources, and whether it succeeded.
You can browse and filter events in the console, look them up with the API or the ezgh CLI,
and run SQL over them with Trails Query.
Event format
Every field of a Trails event, with an example.
Look up events
Filter events in the console, the CLI and the API.
Trails Query
Run SQL over your events, asynchronously.
What Trails records
Events come from these event sources:
| Event source | Activity |
|---|---|
organizations.ezghcloud.com |
Organizations and projects |
iam.ezghcloud.com |
Users, groups, bots, policies, API keys, invitations, SSO and SCIM settings |
signin.ezghcloud.com |
Sign-in, sign-out and account operations |
billing.ezghcloud.com |
Billing details, payment methods, invoices and costs |
ocr.ezghcloud.com |
OCR models, processors and document processing |
trails.ezghcloud.com |
Reading Trails and running Trails Query |
| Activity | Recorded |
|---|---|
| A call that changes something, whether it succeeds or fails | Yes (readOnly: false) |
A call that only reads, such as GetProcessor or LookupEvents |
Yes (readOnly: true) |
A call refused because the caller lacks permission (403 access_denied) |
Yes, with errorCode |
A 400 error returned to a member of the organization |
Yes, with errorCode |
| A change the platform makes to your resources on its own | Yes (eventType: ServiceEvent) |
A request without valid credentials (401) |
No |
A request for an organization the caller doesn’t belong to (404) |
No |
| A write from a browser session refused by the Origin check | No |
Polling a query’s status (GetQuery) or reading the query schema (GetQuerySchema) |
No |
An event is recorded only once the caller is known to be a member of the organization. Requests that no one can be held to, and probes of organizations you don’t belong to, don’t appear in anyone’s Trails.
Trails never records passwords, tokens, cookies, client secrets or payment details. Request
fields that could hold a secret are replaced with HIDDEN_DUE_TO_SECURITY_REASONS. For document
processing, Trails records the page count, size and file type, never the document’s content,
file name or extracted text.
Retention
Trails doesn’t expire events. Trails Query results are kept for 7 days after the query finishes.
Who can use Trails
Trails is organization-wide. Access is controlled by these IAM actions:
| Action | Allows | In AdministratorAccess |
In ReadOnlyAccess |
|---|---|---|---|
audit.events.list |
Look up events and read single events | Yes | Yes |
audit.queries.run |
Start Trails queries, and read the query schema | Yes | Yes |
audit.queries.get |
See your own queries’ status and results | Yes | Yes |
audit.queries.list |
See everyone’s queries and their results | Yes | Yes |
audit.queries.cancel |
Cancel queries you can see | Yes | No |
The root user can do all of these. API keys act with their owner’s access. See IAM for policies.