libLogit

Developer Instructions

This guide describes the intended v1 Beta user workflow. Alpha bindings may not support every field yet, but they should move toward this contract.

Install Or Import

Use the package manager for your language when an artifact exists. During Alpha, some bindings are consumed directly from this repository.

Language Current route
Python python -m pip install -e . from a checkout; package metadata exists.
C/C++ CMake install/export from the repository.
C# NuGet package metadata and artifact inspection exist.
Java Maven package metadata and jar inspection exist.
JavaScript npm package metadata and installed-tarball smoke coverage exist.
Go Go module/package docs exist.
Kotlin Maven companion package verification exists.

Beta readiness requires each supported binding to provide a normal install path, a direct example, a config-loaded example, and conformance evidence.

For the real per-binding install picture, including artifact maturity and what is still partial, use Install and package status.

Create A LOGIT

Create one logger for the application or one logger per subsystem.

LOGIT AppLog = []
AppLog.localPath = "logs/app.log"
AppLog.level = INFO

A blank LOGIT should be safe to instantiate. It may write to console by default, but it should not require a config file before first use.

Think of a LOGIT as a logging device owned by your application. You create it, point it at a destination, choose a level, and then call it whenever you want to record an event.

Configure Output Location

Use an exact file path:

AppLog.localPath = "logs/app.log"

Use directory mode when supported:

AppLog.outputDirectory = "logs"
AppLog.pathMode = "directory"

In directory mode, the binding derives a file name from the logger name. For example, AppLog may write to logs/AppLog.log.

This is the preferred product story for Beta because it keeps setup simple:

LOGIT AppLog = []
AppLog.outputDirectory = "logs"
AppLog.level = INFO

That is the shortest route from “I imported the SDK” to “my project now keeps logs in an organized place.”

The Minimum Useful Setup

If your goal is “give me usable logs right now,” the Beta story should be this simple:

LOGIT AppLog = []
AppLog.outputDirectory = "logs"
AppLog.level = INFO

That setup should give the project:

Everything else in the SDK builds on top of that first working setup.

Configure Level

The portable level order is:

trace < debug < info < warn < error < fatal

When AppLog.level = "info", trace/debug events are ignored and info or higher events are written.

Configure Sinks

Sink Beta contract
Console Immediate developer-visible output.
Local file UTF-8 append output with parent-directory creation where safe.
Remote path Alpha-compatible remote-path-as-file behavior, such as network shares.
Database SQLite-backed local store for SQL-readable retained logs.
Network transport Beta-track design item for HTTP/TCP/UDP or other future transports.

Configure Rotation And Retention

The SDK should support bounded local history. A LOGIT may cap output by record count, age, byte budget, file size, or file count depending on sink type and binding maturity.

{
  "name": "AppLog",
  "localPath": "logs/app.log",
  "level": "info",
  "rotation": {
    "maxBytes": 1048576,
    "maxFiles": 5
  },
  "retention": {
    "maxRecords": 5000
  }
}

Configure Local SQL Storage

The Alpha showcase uses SQLite because it is embedded, portable, and readable by standard SQL tools.

{
  "name": "AuditLog",
  "databasePath": "logs/audit.sqlite",
  "sinks": ["console", "database"],
  "retention": {
    "maxRecords": 10000
  }
}

The viewer should open that store and support filtering by logger, level, time, and message text.

The important product point here is that libLogit is not only trying to write logs. It is trying to leave behind a retained log store that is still useful after the process exits.

Configure Remote Output

Alpha treats a remotePath as a file path. This supports network shares and other filesystem-mounted destinations:

AppLog.remotePath = "\\\\logserver\\share\\app.log"

True remote transports are Beta work. They need explicit transport names, authentication handling, retry/backoff policy, failure semantics, and tests that do not depend on one developer machine.

Troubleshooting

Symptom Check
No file appears Confirm localPath or directory mode is set and the process can create the parent directory.
Logs are missing Confirm the event level is at or above the configured threshold.
JSON output is unexpected Confirm the binding supports format = "json" and that payloads are serializable.
Remote path fails Treat Alpha remote output as filesystem output; verify the share or mount works outside libLogit.
Viewer shows no rows Confirm the database sink is enabled and the selected database path matches the logger config.
Language examples differ Compare behavior, not punctuation; each binding should follow native syntax while preserving the contract.

What To Expect In Alpha Versus Beta

Alpha is the functional example:

Beta is the hardening release: