# Write logs that explain an operation

Source: https://zotonic.com/docs/1640/write-logs-that-explain-an-operation

URI: https://zotonic.com/id/1640

Language: en

Log the operation and its result with structured fields. Include an identifier that helps connect the message to a resource or job, without logging credentials or complete private request data.

```erlang
?LOG_ERROR(#{
    text => <<"Garden update failed">>,
    in => mod_garden,
    result => error,
    reason => Reason
}).
```

Use the logging macros from `zotonic_core/include/zotonic.hrl` when that header is already included. Branch on the actual result of the operation before logging success or failure.

Read logs and collect useful evidence
-------------------------------------

**Access needed:** Site log permission or server log access.

::: {.aside}
Container and host service logs may be stored in different places.
:::

1. Record the time, environment, hostname, affected page, and action that failed.
2. Check the relevant site log or service log around that time.
3. Identify the first relevant error and its module, request or correlation identifier, and repeated causes.
4. Compare with the last deployment or configuration change.
5. Reproduce once with safe test data when possible and note the expected and actual result.
6. Share a short redacted excerpt and the reproduction steps with the responsible operator or developer.

Do not publish complete configuration dumps, cookies, authorization headers, password-reset URLs, or message bodies. Retain detailed logs in the controlled incident record.

More logging is not always better: temporary debug logging can expose data or fill disks. If enabled for diagnosis, record the change and turn it off afterwards.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/1640?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/1640?language=en>)
