Capstone A: the model

The first capstone builds a report from a log file, one lesson at a time. This lesson fixes the data: one entry of the log, its text form, and a file the program writes itself so that the next lessons have input that is the same on every machine.

The record

A log entry is a moment, a level and a message. A positional record gives the three properties, value equality and a readable ToString without a line of code:

var sample = new LogLine(new DateTime(2024, 3, 10, 9, 30, 0, DateTimeKind.Utc), "INFO", "started"); Console.WriteLine(sample); Console.WriteLine(sample == new LogLine(new DateTime(2024, 3, 10, 9, 30, 0, DateTimeKind.Utc), "INFO", "started")); record LogLine(DateTime At, string Level, string Message);

dotnet run

LogLine { At = 03/10/2024 09:30:00, Level = INFO, Message = started }
True

The two entries compare equal because the record compares its values, which is what a log entry is: two lines with the same time, level and message are the same event. The default ToString is for a debugger, not for a file; the file format is written by hand, which is the next section.

Writing the file

The line format is the time in ISO form with a Z, the level padded to five characters and the message. The padding makes the columns line up and is part of the format, so the parser of the next lesson can rely on it:

var path = Path.Combine(Path.GetTempPath(), "aredel-capstone.log"); var lines = new[] { new LogLine(new DateTime(2024, 3, 10, 9, 30, 0, DateTimeKind.Utc), "INFO", "started"), new LogLine(new DateTime(2024, 3, 10, 9, 30, 1, DateTimeKind.Utc), "WARN", "slow request ms=120"), new LogLine(new DateTime(2024, 3, 10, 9, 30, 2, DateTimeKind.Utc), "ERROR", "failed id=7"), new LogLine(new DateTime(2024, 3, 10, 9, 30, 3, DateTimeKind.Utc), "INFO", "done"), }; File.WriteAllLines(path, lines.Select(Format)); Console.WriteLine($"wrote {lines.Length} lines"); Console.WriteLine($"bytes {new FileInfo(path).Length}"); foreach (var line in File.ReadLines(path)) { Console.WriteLine(line); } File.Delete(path); static string Format(LogLine line) => $"{line.At:yyyy-MM-ddTHH:mm:ss}Z {line.Level,-5} {line.Message}"; record LogLine(DateTime At, string Level, string Message);

dotnet run

wrote 4 lines
bytes 153
2024-03-10T09:30:00Z INFO started
2024-03-10T09:30:01Z WARN slow request ms=120
2024-03-10T09:30:02Z ERROR failed id=7
2024-03-10T09:30:03Z INFO done

The file has 153 bytes: four lines of text and the line breaks. The Z is literal in the format string, and the time is formatted with the invariant culture, so the file reads the same on a machine with a German locale. A file format that a program parses itself must not depend on the culture of the process.

Reading it back

File.ReadLines returns the lines one at a time, which is the form the large-file lesson needs. The program prints the file it just wrote and deletes it:

The second half of the same program prints the lines it just wrote and deletes the file. File.ReadLines returns the lines one at a time, which is the form the large-file lesson needs.

The two spaces after INFO are the padding of the five-character column: INFO is four characters and the format wrote one. ERROR fills the column and has a single space before the message, which is the separator that is always there. A parser therefore splits on the first two spaces and takes the rest as the message, which the next lesson does.

The shape of the line

PartExampleRule
time2024-03-10T09:30:00ZISO 8601, UTC, seconds
levelINFO one of INFO, WARN, ERROR, padded to five
messageslow request ms=120free text to the end of the line

The next lesson parses this shape with TryParse and counts the lines that do not follow it. A file of this course is always written under Path.GetTempPath() and removed before the program ends, so no lesson leaves a file in the repository.

Exercises

  1. Add a fifth entry with a message that contains spaces and confirm that the format keeps it whole.
  2. Change the padding to six and compute the new byte count before running.
  3. Format the time with milliseconds and add that part to the rule table.
  4. Write the same entries as JSON with the lesson on writing JSON and compare the size.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is a positional record?

    Answer

    A class with a property per parameter, value equality and ToString

    The lesson declares LogLine in one line and compares two instances by value.

  2. What does the format {line.Level,-5} do?

    Answer

    Writes the level left-aligned in five characters

    It is why INFO has two trailing spaces and ERROR none.

  3. What does this program print? var at = new DateTime(2024, 3, 10, 9, 30, 0, DateTimeKind.Utc); Console.WriteLine($"{at:yyyy-MM-ddTHH:mm:ss}Z");

    Answer

    2024-03-10T09:30:00Z

    The custom format writes the parts in that order and the Z is literal.

  4. What does this program print? Console.WriteLine($"[{"INFO",-5}]");

    Answer

    [INFO ]

    A negative width left-aligns, so the space follows the text.

  5. Why does the format string write the time in UTC?

    Answer

    A log read on another machine has one unambiguous time

    A local time without an offset cannot be placed on a timeline.

  6. What does File.ReadLines return?

    Answer

    A lazy sequence of the lines

    It reads a line when the loop asks for one, which the large-file lesson uses.

  7. How many bytes did the four lines take?

    Answer

    153

    The measured line on the page is bytes 153.

  8. Why does the program delete the file at the end?

    Answer

    The file is a demonstration and the temp folder is not the repository

    A lesson leaves no file behind; the next lesson writes its own input.

  9. What does this program print? var values = new[] { "a", "b" }; Console.WriteLine(values.Select(x => x.Length).Sum());

    Answer

    2

    Two strings of one character each sum to two.

  10. Where does the lesson write the file?

    Answer

    Path.GetTempPath(), with a fixed name

    That is /tmp/ here, and the path is built with Path.Combine.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev