Enhance log component documentation

Author: lovasoa

examples/official-site/sqlpage/migrations/66_log_component.sql

@@ -1,58 +1,61 @@
 INSERT INTO component(name, icon, description) VALUES 
-('log', 'logs', 'A Component to log a message to the Servers STDOUT or Log file on page load');
+('log', 'logs', 'A component that writes messages to the server logs.
+When a page runs, it prints your message to the terminal/console (standard error).
+Use it to track what happens and troubleshoot issues.
+
+### Where do the messages appear?
+
+- Running from a terminal (Linux, macOS, or Windows PowerShell/Command Prompt): they show up in the window.
+- Docker: run `docker logs <container_name>`.
+- Linux service (systemd): run `journalctl -u sqlpage`.
+- Output is written to [standard error (stderr)](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)).
+');
 
 INSERT INTO parameter(component, name, description, type, top_level, optional) SELECT 'log', * FROM (VALUES
     -- top level
-    ('message', 'The message that needs to be logged', 'TEXT', TRUE, FALSE),
-    ('priority', 'The priority which the message should be logged with. Possible values are [''trace'', ''debug'', ''info'', ''warn'', ''error''] and are not case sensitive. If this value is missing or not matching any possible values, the default priority will be ''info''.', 'TEXT', TRUE, TRUE)
+    ('message', 'The text to write to the server logs. It is printed when the page runs.', 'TEXT', TRUE, FALSE),
+    ('level', 'How important the message is. One of ''trace'', ''debug'', ''info'' (default), ''warn'', ''error''. Not case-sensitive. Controls the level shown in the logs.', 'TEXT', TRUE, TRUE)
 ) x;
 
 INSERT INTO example(component, description) VALUES
 ('log', '
-### Hello World
+### Record a simple message
 
-Log a simple ''Hello, World!'' message on page load.
+This writes "Hello, World!" to the server logs.
 
 ```sql
-SELECT ''log'' as component,
-        ''Hello, World!'' as message
+SELECT ''log'' as component, ''Hello, World!'' as message;
 ```
 
-Output example:
+Example output:
 
-```
-[2025-09-12T08:33:48.228Z INFO  sqlpage::log from file "index.sql" in statement 3] Hello, World!
+```text
+[2025-09-13T22:30:14.722Z INFO  sqlpage::log from "x.sql" statement 1] Hello, World!
 ```
 
-### Priority
+### Set the importance (level)
 
-Change the priority to error.
+Choose how important the message is.
 
 ```sql
-SELECT ''log'' as component,
-        ''This is a error message'' as message,
-        ''error'' as priority
+SELECT ''log'' as component, ''error'' as level, ''This is an error message'' as message;
 ```
 
-Output example:
+Example output:
 
-```
-[2025-09-12T08:33:48.228Z ERROR sqlpage::log from file "index.sql" in header] This is a error message
+```text
+[2025-09-13T22:30:14.722Z ERROR sqlpage::log from "x.sql" statement 2] This is an error message
 ```
 
-### Retrieve user data
+### Log dynamic information
 
-```sql
-set username =  ''user'' -- (retrieve username from somewhere)
+Include variables like a username.
 
-select ''log''							  as component,
-        ''403 - failed for '' || coalesce($username, ''None'') as output,
-        ''error''							  as priority;
-```
-
-Output example:
+```sql
+set username = ''user''
 
-```
-[2025-09-12T08:33:48.228Z ERROR sqlpage::log from file "403.sql" in statement 7] 403 - failed for user
+select ''log'' as component,
+        ''403 - failed for '' || coalesce($username, ''None'') as message,
+        ''error'' as level;
 ```
 ')