Logging

Logging gives an application a lasting record of what it did, without a logging stack of its own. The application writes log entries and counters through the package's client. Turn Zero Cloud stores them and returns them when you read them. It also writes its own events about your application to the same store.

Use it when

Use Logging when an application needs to record what happened, as a message with a level and a few named fields. Use it also to keep a count without scanning records to work it out: requests served, uploads completed, or sign-ins rejected.

Do not write end-user content into a record. A field contains only what the application deliberately puts there.

What it provides

  • Log entries and counters. An entry has a level, a message, and optional scalar fields. Counters are added up into hourly and daily totals.
  • A client, LogClient, with no dependencies, published as the npm package @turnzero/logging. It has log.debug, log.info, log.warn, log.error, and count. Use the library shows how to copy it into app/lib/logging/, declare it as file:lib/logging, and install it with npm install.
  • Background delivery. The client takes the environment when you construct it: a hosted process reads it from APP_ENVIRONMENT, and a local run sets local. It sends records in batches without blocking the caller. It waits at most ten seconds for each batch's response, so a stalled connection cannot block it. Records it cannot deliver go to its fallback output, and buffered records can be lost. Read logs and counters states the batch limits, the fallback's lines, and flushing at shutdown.
  • A stored stream per environment. Each batch specifies its environment. Under the application's platform credential, that environment must be the credential's environment. The one exception is local, which only a development credential may write, so a local run writes to the local stream and never to production. Under a minted token the batch specifies the environment, and an x-turnzero-cloud-environment header, if sent, must specify the same one.
  • A source on every record. The source tells your records from the platform's, as Read logs and counters lists. The source harness marks the runtime harness's connection records, sent from your application's own process under its own credential.
  • Reads and deletion through your tool. Management actions read entries and counter totals. purge_logs, approved in the browser, removes the records for the application or one of its environments. delete_environment removes the development environment's entries and counter totals and reports how many it removed. delete_application removes every environment's.
  • Size, rate, and retention limits, and a per-plan limit on the bytes of your own entries one environment keeps. A batch that would pass that limit is refused log_capacity_reached, and the refusal is counted in logging.refused_capacity. Read logs and counters states each plan's limit and the retention periods.

A test double ships at the package's testing subpath, @turnzero/logging/testing. createLoggingDouble takes the place of the logging service behind the unchanged client. It keeps the entries and counters for a test to read back. Test your application locally shows it in use.

Availability

Version 0.10.2 is the package's current version, and list_library reports the version the platform currently publishes. The entry includes the testing subpath from version 0.7.0.

The entry contains the package's product statement, its detailed contract, its integration guide, and the compiled client. Turn Zero Cloud runs the logging service, with reads through read_logs and read_counters. read_logs reads the production stream when environment is omitted, and its all source returns every stored source together. read_counters requires an environment and returns at most 1,000 rows of totals.

Database stores application records, and Storage stores files. Logging records application activity.