# Logs, events and monitor

> The three read verbs — what an app printed, what the platform did, and what a resource is using

URL: https://pier.run/docs/logs-events-monitor

Three verbs answer three different questions about the current environment. Each takes a
[ref](/docs/cli/refs) or, with none, opens a picker.

| Question                    | Verb           | Source                                                                      |
| --------------------------- | -------------- | --------------------------------------------------------------------------- |
| What did my app print?      | `pier logs`    | the containers' stdout/stderr and the Postgres server log                   |
| What did the platform do?   | `pier events`  | the platform's own record: deploys, scaling, provisioning, pauses, failures |
| What is it using right now? | `pier monitor` | CPU, memory, requests, latency, storage, egress                             |

## Logs

```bash
pier logs api --tail 5
```

```text title="output"
  api · the last hour
2026-08-30 22:31:46.362  INFO     [t5dk7]  2026/08/30 14:31:46 [tick 8] hello-web running on app-01a05313-e5c2-70df-acd5-6de1595d13b8-58946dd54b-t5dk7
2026-08-30 22:31:51.366  INFO     [t5dk7]  2026/08/30 14:31:51 [tick 9] hello-web running on app-01a05313-e5c2-70df-acd5-6de1595d13b8-58946dd54b-t5dk7
2026-08-30 22:31:56.366  INFO     [t5dk7]  2026/08/30 14:31:56 [tick 10] hello-web running on app-01a05313-e5c2-70df-acd5-6de1595d13b8-58946dd54b-t5dk7
2026-08-30 22:32:01.370  INFO     [t5dk7]  2026/08/30 14:32:01 [tick 11] hello-web running on app-01a05313-e5c2-70df-acd5-6de1595d13b8-58946dd54b-t5dk7
2026-08-30 22:32:06.374  INFO     [t5dk7]  2026/08/30 14:32:06 [tick 12] hello-web running on app-01a05313-e5c2-70df-acd5-6de1595d13b8-58946dd54b-t5dk7

```

```bash
pier logs api --follow                      # stream until Ctrl-C
pier logs api --since 6h --level ERROR      # a window, one level
pier logs api --query "timeout"             # search the message
pier logs api/canary/2                      # one instance of one target
pier logs main                              # the Postgres server log
pier logs --all --follow                    # every app in the environment
```

Lines carry the instance suffix (`[vg59g]`) so a multi-instance target reads as one stream.
`--since` takes a duration or an RFC 3339 time; `--utc` switches timestamps. Logs are kept
per target; a rolled instance's lines stay searchable.

## Events

```bash
pier events --limit 8
```

```text title="output"
                                                                         
 TIME    KIND   ACTION            TITLE                           ACTOR  
                                                                         
 2s ago  intent intent.transition app_target running (succeeded)  system 
 30s ago intent intent.transition app_target running (converging) system 
 32s ago intent intent.transition app_target running (executing)  system 
 32s ago intent intent.transition volume running (succeeded)      system 
 32s ago intent intent.transition volume running (executing)      system 
 1m ago  intent intent.transition app_target running (succeeded)  system 
 1m ago  intent intent.transition app_target running (executing)  system 
 2m ago  intent intent.transition app_target running (succeeded)  system 
                                                                         

```

| Kind        | Means                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `milestone` | a phase of a deploy or provision started or completed                                                       |
| `intent`    | the platform's state machine moved a resource (`running`, `suspended`, `converging`, `succeeded`, `failed`) |
| `activity`  | something a person or an integration did: a config apply, a pause, a push                                   |

```bash
pier events api                        # one resource
pier events --kind intent --severity error --since 24h
pier events --operation op_…           # everything one operation did, as a tree
pier events --watch                    # keep printing
pier events --all-projects --json      # the workspace, machine-readable, paginated with --after
```

When a deploy fails, `pier events api --severity error` is the first place to look; the
`intent` row carries the platform's reason, the `milestone` rows the phase it failed in.

## Monitor

```bash
pier monitor api
```

```text title="output"

  api (1/1 ready)
  CPU          1.2%
  Memory       9.6%
  Requests     0.00/s
  Errors       — no data
  Latency p95  — no data
  Egress 24h   170 B

  updated just now

```

```bash
pier monitor --all                     # every resource in the environment, one line each
pier monitor api --range 24h           # a window instead of the live snapshot
pier monitor api --metric cpu_pct --by-instance
pier monitor main                      # connections, storage, cache hit ratio
pier monitor uploads                   # objects, storage, egress
```

```text title="output"

  Apps
                                                   
 NAME READY CPU  MEM  REQ/S  ERRORS P95 EGRESS 24H 
                                                   
 api  1/1   1.2% 9.6% 0.00/s —      —   170 B      
                                                   

  Postgres
                                  
 NAME CPU  MEM STORAGE EGRESS 24H 
                                  
 main 1.5% 12% —       6 KB       
                                  

  Buckets
                                            
 NAME    STORAGE OBJECTS REQ 24H EGRESS 24H 
                                            
 uploads 0 B     0       —       0 B        
                                            

  Volumes
                                        
 NAME USED CAPACITY           SNAPSHOTS 
                                        
 data —    1.00 GB (declared) 0         
                                        

  Sites
                               
 NAME REQ/S REQ 24H EGRESS 24H 
                               
 www  —     —       —          
                               

```

Measures are per target and per instance; `--range` accepts `1h`, `6h`, `24h`, `7d`, `30d`.
Egress for buckets and sites is read from the same counters that billing meters.

## See also

[`pier logs`](/docs/cli/reference/logs) · [`pier events`](/docs/cli/reference/events) ·
[`pier monitor`](/docs/cli/reference/monitor) · [Scripting](/docs/cli/scripting)