Console and logging

Package names on this page are preview naming and may change before launch.

Printing

print will be a built-in function. It will take one value, text, an i64 integer or a bool, and write it to standard output followed by a line break. Integers will be written in decimal, and a bool as true or false.

# main.ael
main main() {
    let attempts: i64 = 3;
    print("Checking the queue");
    print(attempts);
    print(true);
}

• print will be a name you cannot declare again.
• It will write to the console on desktop and server targets. On a microcontroller board, print will need an output that the board provides, such as its serial port (UART); a board program that prints without one will be refused when you build. Microcontroller boards describes the boards.

Console input

A console agent will need no server. When you run it, its typed input will come from one of three places:

• an argument on the command line;
• text piped into standard input;
• the console, where the agent asks for input and reads what you type.

The program will not wait for more input when you gave it an argument. It will be able to answer once and exit, or run a loop that you write, asking again until its own exit condition, the end of the input or a cancellation. Blank input, input that is too long and input that is not valid UTF-8 will each give a defined result rather than a crash.

./build/support "Where is my order?"
cat questions.txt | ./build/support

To turn the same agent into a REST API, you will add the server/http package and declare routes; remove them to go back to console-only. See Services and APIs.

Standard output and standard error

When a program writes a machine-readable result, a human summary will never be mixed into it; the summary will go to its own channel. The exit status will stay the program's own.

The time and token summary

Time and token usage will be reported by default on every channel: the command line, and the HTTP, gRPC, WebSocket and socket servers you add. On the command line, a one-line summary of the run's elapsed time and its input, output and total tokens will go to standard error when the run ends, including when it fails or is cancelled.

• A program that calls no model will report zero tokens only when it is known that no model was called. Usage that could not be counted will be shown as unknown, never as zero.
• You will be able to turn off the whole summary, the time alone, the tokens alone, each token count on its own, or one channel.
• Turning a field off will hide it; it will not disable the limits behind it. Budgets will still be counted and enforced.

Reporting, logs and replay describes how each server channel reports time and tokens.

Structured logs

Structured logs will go to the console, a file, or custom or remote sinks, with redaction, rotation and retention.

Every log event will carry:

• its severity and kind;
• the identity of the run, the agent and the session it belongs to, and the trusted tenant identity where there is one;
• a time read from a clock that only moves forward, and optionally the wall-clock time;
• fields that correlate it with other events.

Sinks

You will route events to several sinks at once, and filter them by severity and by agent. Logging and monitoring describes where logs go on each kind of target.

Bounded and visible

• Every sink will have a bounded queue and a stated policy for what happens when it is full.
• A sink that fails, stalls or runs out of disk will not block your program's work or its shutdown. The failure will be reported through a fallback route, and a sink will never log its own failure in a loop.
• On the smallest boards, logging will need no file system.

Redaction

• By default, logs will record what happened, not the data: prompts, inputs and outputs will be left out.
• Secrets and protected configuration values will be redacted before an event reaches any sink.
• You will be able to record selected fields of your own data, under a retention and access policy you declare.

Audit records

Records of security and platform events will be kept apart from your application's logs. Your code will control its own logs, within its permissions; it will not be able to alter or erase audit records.

Not yet described

How you will declare sinks, filters and the summary settings, and the names of the logging operations, will be published when the library is final.