Skip to content

Commit 056de65

Browse files
hugobaraunahugobarauna
authored
Docs for code execution audit logs (#3078)
1 parent 6c2c430 commit 056de65

File tree

2 files changed

+147
-0
lines changed

2 files changed

+147
-0
lines changed

‎docs/teams/audit_logs.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# How to configure audit logs for code execution
2+
3+
This guide shows you how to configure Livebook to log who ran what code and when.
4+
5+
This is useful when your team uses Livebook to execute code against production systems and needs to maintain audit logs of code execution.
6+
7+
## Configure audit logging
8+
9+
Livebook can capture three key pieces of information in audit logs:
10+
11+
- Timestamp
12+
- User identity
13+
- Code executed
14+
15+
Livebook includes timestamps in logs by default, but user identity and code execution need to be added via configuring the following environment variables.
16+
17+
### Set log metadata
18+
19+
Configure the `LIVEBOOK_LOG_METADATA` environment variable:
20+
21+
```
22+
LIVEBOOK_LOG_METADATA="users,code,session_mode,event"
23+
```
24+
25+
Each key adds the following information to the log:
26+
27+
- `users` - User identity (name and email)
28+
- `code` - The code being executed
29+
- `session_mode` - Execution context: `default` for regular notebook sessions, `app` for local app previews (different from deployed Livebook apps)
30+
- `event` - Set to `code.evaluate` for code evaluaton log entries
31+
32+
### Set the log format to JSON
33+
34+
Configure JSON log format for easier parsing in log aggregators:
35+
36+
```
37+
LIVEBOOK_LOG_FORMAT=json
38+
```
39+
40+
### Set the log level to info
41+
42+
Code execution logs require the `info` log level or higher. Configure the log level:
43+
44+
```
45+
LIVEBOOK_LOG_LEVEL=info
46+
```
47+
48+
## Understand the code execution log format
49+
50+
After configuring the environment variables, your logs will contain entries like this:
51+
52+
```
53+
{"message":"Evaluating code","time":"2025-10-06T19:19:19.851Z","metadata":{"code":"1 + 1","event":"code.evaluate","users":[{"id":"1","name":"Hugo Baraúna","email":"[email protected]"}],"session_mode":"default"},"severity":"info"}
54+
{"message":"Evaluating code","time":"2025-10-06T19:19:40.131Z","metadata":{"code":"query = from u in User, select: u.name\nRepo.all(query)","event":"code.evaluate","users":[{"id":"1","name":"Hugo Baraúna","email":"[email protected]"}],"session_mode":"default"},"severity":"info"}
55+
{"message":"Evaluating code","time":"2025-10-06T19:19:59.748Z","metadata":{"code":"Repo.all(Organization)","event":"code.evaluate","users":[{"id":"1","name":"Hugo Baraúna","email":"[email protected]"}],"session_mode":"default"},"severity":"info"}
56+
```
57+
58+
Here's one of those log entries formatted for readability:
59+
60+
```
61+
{
62+
"message": "Evaluating code",
63+
"time": "2025-10-06T19:19:40.131Z",
64+
"metadata": {
65+
"code": "query = from u in User, select: u.name\nRepo.all(query)",
66+
"event": "code.evaluate",
67+
"users": [
68+
{
69+
"id": "1",
70+
"name": "Hugo Baraúna",
71+
"email": "[email protected]"
72+
}
73+
],
74+
"session_mode": "default"
75+
},
76+
"severity": "info"
77+
}
78+
```
79+
80+
Each log entry contains three key pieces of audit information:
81+
82+
- **When** - The `time` property contains an ISO 8601 timestamp with UTC timezone (e.g., `2025-10-03T20:49:22.231Z`).
83+
- **Who** - The `metadata.users` array contains user objects with `id`, `name`, and `email`. Multiple users may appear when collaborating on the same notebook session.
84+
- **Code** - The `metadata.code` property contains the exact code that was executed. Multi-line code includes newline characters (`\n`).
85+
86+
## Filtering code execution logs
87+
88+
If you're sending Livebook logs to a log aggregator, you can filter specifically for code execution events using the `metadata.event` field:
89+
90+
```
91+
metadata.event: "code.evaluate"
92+
```
93+
94+
This filter isolates code execution audit logs from other log entries, making it easier to track and analyze code execution activity in your monitoring tools.
95+
96+
## User identity sources
97+
98+
User identities come from the authentication methods configured in your Livebook Teams organization. The following authentication methods are supported:
99+
100+
* **Livebook Teams account** - Members of your Livebook Teams organization authenticate using their Teams accounts
101+
102+
* **Email domain** - Users authenticate using email accounts from specific domains, such as your company's Google Workspace domain
103+
104+
* **OpenID Connect Single Sign-On (SSO)** - Users authenticate via an OpenID Connect provider, such as Okta, Microsoft Entra, or Keycloak
105+
106+
When users authenticate through any of these providers, their identity information (name and email) becomes available in the audit logs.
107+
108+
## Logs in deployed Livebook apps
109+
110+
Code execution logs are **not** generated when users interact with deployed Livebook apps. This is intentional.
111+
112+
When someone uses a deployed Livebook app, they don't see or decide which code executes—they simply interact with an application interface. The code execution happens behind the scenes as part of the app's functionality.
113+
114+
Code execution audit logs are designed for contexts where users can see and choose to execute code:
115+
116+
* **Regular notebook sessions** - Users write and run code in notebooks
117+
* **App previews** - Users preview how their notebook looks as an app while still in the notebook editor (using the preview button)
118+
119+
In these scenarios, users are making deliberate decisions about what code to execute, making audit logging meaningful and appropriate.
120+
121+
If you need to log events within a deployed Livebook app, use Elixir's `Logger` module directly in your notebook code to log whatever information is relevant to your use case.
122+
123+
## Troubleshooting
124+
125+
### Logs aren't appearing
126+
127+
If you don't see code execution logs after configuration:
128+
129+
1. **Verify log level** - Ensure `LIVEBOOK_LOG_LEVEL=info` is set. Code execution logs won't appear at higher levels like `warning` or `error`.
130+
131+
2. **Check environment variables** - Restart Livebook after setting environment variables. Changes require a restart to take effect.
132+
133+
3. **Confirm authentication** - User identity only appears when users are authenticated. Verify your authentication method is configured correctly in your Livebook Teams organization.
134+
135+
### Verify configuration is working
136+
137+
To confirm audit logging is configured correctly:
138+
139+
1. Execute a simple code cell (e.g., `1 + 1`) in a notebook
140+
2. Check your logs for an entry with:
141+
- `"message": "Evaluating code"`
142+
- `"metadata.event": "code.evaluate"`
143+
- `"metadata.users"` containing your user information
144+
- `"metadata.code"` containing `"1 + 1"`
145+
146+
If all these fields appear, your audit logging is working correctly.

‎mix.exs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,7 @@ defmodule Livebook.MixProject do
269269
"docs/teams/shared_file_storages.md",
270270
{"docs/teams/git_file_storage.md", title: "Open notebooks from a private Git"},
271271
{"docs/teams/phoenix_integration.md", title: "How-to integrate with a Phoenix app"},
272+
"docs/teams/audit_logs.md",
272273
{"docs/teams/teams_concepts.md", title: "Livebook Teams concepts"},
273274
"docs/authentication/basic_auth.md",
274275
"docs/authentication/cloudflare.md",

0 commit comments

Comments
 (0)