Skip to content

docs(timestamps): fix outdated enabling timestamping section #787

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Chennamma-Hotkar wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(timestamps): fix outdated enabling timestamping section #787

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 11 additions & 27 deletions docs/developer-guide/timestamps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,53 +40,37 @@ Timestamp logging is now handled through a fixed schema using zerolog. The previ

## How to enable timestamping

In order to capture the timestamps, a separate `containerd-shim` and container runtime must be configured in your system.
Timestamping is enabled via urunc's configuration file at `/etc/urunc/config.toml`:

To create the "timestamping" version of `containerd-shim-urunc-v2`:

```bash
sudo tee -a /usr/local/bin/containerd-shim-uruncts-v2 > /dev/null << 'EOT'
#!/bin/bash
URUNC_TIMESTAMPS=1 /usr/local/bin/containerd-shim-urunc-v2 $@
EOT
sudo chmod +x /usr/local/bin/containerd-shim-uruncts-v2
```toml
[timestamps]
enabled = true
destination = "/var/log/urunc/timestamps.log"
```

To add the "timestamping" urunc to containerd config:
No separate `containerd-shim` or container runtime configuration is required — urunc reads this setting directly at startup.

@cmainas cmainas Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having a separate contianerd entry for urunc and timestamps useful. Please take look at https://urunc.io/configuration/#configuration-file-location to see how this can be enabled (two different urunc shims; one for timestamp)


```bash
sudo tee -a /etc/containerd/config.toml > /dev/null << 'EOT'
# timestamping urunc
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.uruncts]
runtime_type = "io.containerd.uruncts.v2"
container_annotations = ["com.urunc.unikernel.*"]
pod_annotations = ["com.urunc.unikernel.*"]
snapshotter = "devmapper"
EOT
sudo systemctl restart containerd.service
```
If the destination directory does not exist, urunc logs a warning and disables metrics gracefully instead of crashing.

## How to gather timestamps

Now we need to run a unikernel using the new container runtime `uruncts`:
Now we need to run a unikernel with timestamping enabled in the config:

```bash
sudo nerdctl run --rm --snapshotter devmapper --runtime io.containerd.uruncts.v2 harbor.nbfc.io/nubificus/urunc/hello-hvt-rumprun:latest
sudo nerdctl run --rm --snapshotter devmapper --runtime io.containerd.urunc.v2 harbor.nbfc.io/nubificus/urunc/hello-hvt-rumprun:latest
```

The timestamp logs are located at `/tmp/urunc.zlog`:
The timestamp logs are located at `/var/log/urunc/timestamps.log`:

@cmainas cmainas Sep 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change the text here and point to the location defined by the configuration.


```console
$ cat /tmp/urunc.zlog | grep TS
$ cat /var/log/urunc/timestamps.log | grep TS
{"containerID":"faaf830245ffab0df81927cebd7f11065e70c7703121fbc1b11d4bca49bab461","timestampID":"TS00","timestampName":"CR.invoked","timestampOrder":0,"time":1703676366849599657}
{"containerID":"faaf830245ffab0df81927cebd7f11065e70c7703121fbc1b11d4bca49bab461","timestampID":"TS01","timestampName":"CR.unikontainer_created","timestampOrder":1,"time":1703676366850466038}
{"containerID":"faaf830245ffab0df81927cebd7f11065e70c7703121fbc1b11d4bca49bab461","timestampID":"TS02","timestampName":"CR.initial_setup","timestampOrder":2,"time":1703676366850709857}
{"containerID":"faaf830245ffab0df81927cebd7f11065e70c7703121fbc1b11d4bca49bab461","timestampID":"TS03","timestampName":"CR.start_reexec","timestampOrder":3,"time":1703676366850900287}
# ... (rest of the output)
```

> Note: the timestamp destination (`/tmp/urunc.zlog`) is hardcoded for the time being.

## Gathering the timestamps

There are 3 Python utilities inside the `script/performance` directory to help gather the timestamps.
Expand Down