teleport/docs/pages/reference/monitoring/audit.mdx

---
title: Audit Events and Records
description: Reference of Teleport Audit Events and Session Records
---

Teleport logs cluster activity by emitting various events into its audit log.
There are two components of the audit log:

<Tabs>
<TabItem scope={["enterprise", "oss"]} label="Self-Hosted">

- **Cluster Events:** Teleport logs events like successful user logins along
   with metadata like remote IP address, time, and the session ID.
- **Recorded Sessions:** Every SSH, desktop, or Kubernetes shell session is recorded and
   can be replayed later. By default, the recording is done by Teleport Nodes,
   but can be configured to be done by the proxy.

</TabItem>
<TabItem scope={["cloud","team"]} label="Cloud-Hosted">

- **Cluster Events:** Teleport logs events like successful user logins along
   with metadata like remote IP address, time, and the session ID.
- **Recorded Sessions:** Every SSH, desktop, or Kubernetes shell session is recorded and
   can be replayed later. Teleport Cloud manages the storage of session
   recording data.

</TabItem>
</Tabs>

<Admonition type="tip">

You can use
[Enhanced Session Recording with BPF](../../enroll-resources/server-access/guides/bpf-session-recording.mdx)
to get even more comprehensive audit logs with advanced security.

</Admonition>

## Events

<Tabs>
<TabItem scope={["enterprise", "oss"]} label="Self-Hosted">

Teleport supports multiple storage backends for storing audit events. The `dir`
backend uses the local filesystem of an Auth Service host. When this backend is
used, events are written to the filesystem in JSON format. The `dir` backend rotates
the event file approximately once every 24 hours, but never deletes captured events.

For High Availability configurations, users can refer to our
[Athena](../backends.mdx), [DynamoDB](../backends.mdx) or
[Firestore](../backends.mdx) chapters for information on how to
configure the SSH events and recorded sessions to be stored on network storage.
When these backends are in use, audit events will eventually expire and be
removed from the log. The default retention period is 1 year, but this can be
overridden using the `retention_period` configuration parameter.

It is even possible to store audit logs in multiple places at the same time. For
more information on how to configure the audit log, refer to the `storage`
section of the example configuration file in the
[Teleport Configuration Reference](../config.mdx).

Let's examine the Teleport audit log using the `dir` backend. Teleport Auth
Service instances write their logs to a subdirectory of Teleport's configured
data directory that is named based on the service's UUID.

Each day is represented as a file:

```code
$ ls -l /var/lib/teleport/log/bbdfe5be-fb97-43af-bf3b-29ef2e302941

# total 104
# -rw-r----- 1 root root  31638 Jan 22 20:00 2022-01-23.00:00:00.log
# -rw-r----- 1 root root  91256 Jan 31 21:00 2022-02-01.00:00:00.log
# -rw-r----- 1 root root  15815 Feb 32 22:54 2022-02-03.00:00:00.log
```

</TabItem>
<TabItem label="Cloud-Hosted">

Teleport Enterprise Cloud manages the storage of audit logs for you. You can
access your audit logs via the Teleport Web UI by clicking:

**Audit** > **Audit Log**

</TabItem>
</Tabs>

Audit logs use JSON format. They are human readable but can also be
programmatically parsed. Each line represents an event and has the following
format:

```javascript
{
    // Event type. See below for the list of all possible event types.
    "event": "session.start",
    // A unique ID for the event log. Useful for  deduplication.
    "uid": "59cf8d1b-7b36-4894-8e90-9d9713b6b9ef",
    // Teleport user name
    "user": "ekontsevoy",
    // OS login
    "login": "root",
    // Server namespace. This field is reserved for future use.
    "namespace": "default",
    // Unique server ID
    "server_id": "f84f7386-5e22-45ff-8f7d-b8079742e63f",
    // Server Labels
    "server_labels": {
      "datacenter": "us-east-1",
      "label-b": "x"
    }
    // Session ID. Can be used to replay the session.
    "sid": "8d3895b6-e9dd-11e6-94de-40167e68e931",
    // Address of the SSH node
    "addr.local": "10.5.l.15:3022",
    // Address of the connecting client (user)
    "addr.remote": "73.223.221.14:42146",
    // Terminal size
    "size": "80:25",
    // Timestamp
    "time": "2017-02-03T06:54:05Z"
}
```

## Event types

Below are some possible types of audit events.

<Admonition type="tip">

This list is not comprehensive. We recommend exporting audit events to a
platform that automatically parses event payloads so you can group and filter
them by their `event` key and discover trends. To set up audit event exporting,
read [Exporting Teleport Audit Events](../../admin-guides/management/export-audit-events/export-audit-events.mdx).

</Admonition>

| Event Type | Description |
| - | - |
| auth | Authentication attempt. Adds the following fields: `{"success": "false", "error": "access denied"}` |
| session.start | Started an interactive shell session. |
| session.end | An interactive shell session has ended. |
| session.join | A new user has joined the existing interactive shell session. |
| session.leave | A user has left the session. |
| session.disk | A list of files opened during the session. *Requires Enhanced Session Recording*. |
| session.network | A list of network connections made during the session.  *Requires Enhanced Session Recording*. |
| session.command | A list of commands ran during the session.  *Requires Enhanced Session Recording*. |
| session.recording.access | A session recording has been accessed. |
| exec | Remote command has been executed via SSH, like `tsh ssh root@node ls /`. The following fields will be logged: `{"command": "ls /", "exitCode": 0, "exitError": ""}` |
| scp | Remote file copy has been executed. The following fields will be logged: `{"path": "/path/to/file.txt", "len": 32344, "action": "read" }` |
| resize | Terminal has been resized. |
| user.login | A user logged into web UI or via tsh. The following fields will be logged: `{"user": "alice@example.com", "method": "local"}` . |
| app.session.start | A user accessed an application |
| app.session.chunk | A record of activity during an app session |
| join_token.create | A new join token has been created. Adds the following fields: `{"roles": ["Node", "Db"], "join_method": "token"}` |

## Recorded sessions

In addition to logging start and end events, Teleport can also record the entire session.
For SSH or Kubernetes sessions this captures the entire stream of bytes from the PTY.
For desktop sessions the recording includes the contents of the screen.

<Tabs>
<TabItem scope={["enterprise", "oss"]} label="Self-Hosted">

Teleport can store the recorded sessions in an [AWS S3 bucket](../backends.mdx)
or in a local filesystem (including NFS).

The recorded sessions are stored as raw bytes in the `sessions` directory under
`log`. Each session is a protobuf-encoded stream of binary data.

You can replay recorded sessions using the [`tsh play`](../cli/tsh.mdx)
command or the Web UI.

For example, replay a session via CLI:

```code
$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931
```

Print the session events in JSON to stdout:

```code
$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json
```

</TabItem>
<TabItem label="Cloud-Hosted">

Teleport Enterprise Cloud automatically stores recorded sessions.

You can replay recorded sessions using the [`tsh play`](../cli/tsh.mdx)
command or the Web UI.

For example, replay a session via CLI:

```code
$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931
```

Print the session events in JSON to stdout:

```code
$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json
```

</TabItem>
</Tabs>

### Modes

<Admonition type="note">
Available only for SSH sessions and when Teleport is configured with
`auth_service.session_recording: node`.
</Admonition>

Modes define how Teleport deals with recording failures, such as a full disk
error. They are configured per-service at the role level, where the strictest
value takes precedence. The available modes are:

|Mode|After a recording failure|
|----|-------------------------|
|Best effort (`best_effort`)|Disables recording without terminating the session.|
|Strict (`strict`)|Immediately terminates the session.|

If the user role doesn’t specify a recording mode, `best_effort` will be used. Here
is an example of a role configured to use strict mode for SSH sessions:

```yaml
kind: role
version: v5
metadata:
  name: ssh-strict
spec:
  options:
    record_session:
      ssh: strict
```