Document default log output and web server setup

.vale.ini

@@ -3,3 +3,6 @@ MinAlertLevel = suggestion
 
 [*.md]
 BasedOnStyles = Microsoft
+Microsoft.Acronyms = NO
+Microsoft.Headings = NO
+Microsoft.HeadingAcronyms = NO

src/cookbook/configuring-webservers/apache.md

@@ -51,5 +51,7 @@ SetEnv APP_ENV dev
 # ...other settings...
 ```
 
-In the above, note the usage of `SetEnv`. Since the Yii3 application template is using environment variables, this is a possible
+In the above, note the usage of `SetEnv`. Since Yii3 application templates use environment variables, this is a possible
 place to set them. In production environment remember to set `APP_ENV` to `prod`.
+
+See [application logs](general.md#application-logs) for logging configuration.

src/cookbook/configuring-webservers/general.md

@@ -7,6 +7,27 @@ Point the document root of your web server to the `app/public` folder.
 > If you're running your Yii application behind a reverse proxy, you might need to configure
 > [Trusted proxies and headers](../../guide/security/trusted-request.md).
 
+## Application logs
+
+Yii3 application templates write application logs to standard output (`stdout`, or `php://stdout`) by default.
+They don't create application log files. Standard error (`stderr`) requires explicit log target configuration.
+Docker collects container output, but on a server without containers you must configure where that output goes
+or [configure a file target](../../guide/runtime/logging.md#logging-to-files).
+Web server access and error log settings don't configure Yii's log targets.
+
+### PHP-FPM
+
+If your web server uses PHP-FPM, enable worker output capture in the application's PHP-FPM pool configuration:
+
+```ini
+catch_workers_output = yes
+```
+
+Reload PHP-FPM after changing its configuration. PHP-FPM sends worker standard output and standard error to its
+main error log. The `error_log` directive in `php-fpm.conf` sets the destination.
+Without this setting, PHP-FPM redirects both streams to `/dev/null` by default.
+See the [PHP-FPM configuration reference](https://www.php.net/manual/en/install.fpm.configuration.php).
+
 ## Specific server configurations
 
 - [Nginx](nginx.md)

src/cookbook/configuring-webservers/iis.md

@@ -29,3 +29,5 @@ Use the following content:
 ```
 
 Also, [IIS documentation](https://learn.microsoft.com/en-us/iis/) could be useful to configure PHP on IIS.
+
+See [application logs](general.md#application-logs) for logging configuration.

src/cookbook/configuring-webservers/lighttpd.md

@@ -5,3 +5,5 @@ To use [lighttpd](https://www.lighttpd.net/) >= 1.4.24, put `index.php` in the w
 ```
 url.rewrite-if-not-file = ("(.*)" => "/index.php/$0")
 ```
+
+See [application logs](general.md#application-logs) for logging configuration.

src/cookbook/configuring-webservers/nginx-unit.md

@@ -60,5 +60,7 @@ Here is a sample configuration.
 You can also [set up](https://unit.nginx.org/configuration/#php) your PHP environment or supply a custom `php.ini`
 in the same configuration.
 
-Since the Yii3 application template uses environment variables, you can set them in `applications.yii.environment`.
+Since Yii3 application templates use environment variables, you can set them in `applications.yii.environment`.
 In a production environment, remember to set `APP_ENV` to `prod`.
+
+See [application logs](general.md#application-logs) for logging configuration.

src/cookbook/configuring-webservers/nginx.md

@@ -56,5 +56,8 @@ to avoid many unnecessary system `stat()` calls.
 Also, note that when running an HTTPS server, you need to add `fastcgi_param HTTPS on;` so that Yii
 can detect if a connection is secure.
 
-In the above, note the usage of `fastcgi_param APP_ENV`. Since the Yii3 application template is using environment variables,
+In the above, note the usage of `fastcgi_param APP_ENV`. Since Yii3 application templates use environment variables,
 this is a possible place to set them. In production environment remember to set `APP_ENV` to `prod`.
+
+The Nginx `access_log` and `error_log` directives above don't capture PHP-FPM worker output.
+See [application logs](general.md#application-logs) for logging configuration.

src/guide/runtime/logging.md

@@ -15,6 +15,23 @@ Using the Yii logging framework involves the following steps:
 
 In this section, the focus in on the first two steps.
 
+## Default log destination
+
+Yii3 application templates
+([web](https://github.com/yiisoft/app/blob/master/config/common/di/logger.php) and
+[API](https://github.com/yiisoft/app-api/blob/master/config/common/di/logger.php))
+configure `Yiisoft\Log\StreamTarget`, which writes to standard output (`stdout`, or `php://stdout`) by default.
+They don't create application log files, such as `runtime/logs/app.log`.
+`StreamTarget` also supports standard error (`stderr`, or `php://stderr`), but you must configure it explicitly.
+
+This works well with Docker, which [collects container output](https://docs.docker.com/engine/logging/).
+Use `docker logs <container>` to read it when the container's logging driver supports that command.
+
+Without containers, the destination depends on how you start PHP and capture its output.
+For example, PHP-FPM discards worker output by default unless you enable `catch_workers_output`.
+See [web server logging configuration](../../cookbook/configuring-webservers/general.md#application-logs).
+To have Yii write application log files directly, configure a [file target](#logging-to-files).
+
 ## Log Messages
 
 To record log messages, you need an instance of PSR-3 logger.
@@ -130,8 +147,65 @@ learn how to configure and use them.
 * [[\Yiisoft\Log\Target\File\FileTarget]]: saves log messages in files.
 * [[\Yiisoft\Log\Target\Syslog\SyslogTarget]]: saves log messages to syslog by calling the PHP function `syslog()`.
 
-In the following, we will describe the features common to all log targets.
+### Logging to files
+
+To write application logs to a file, install the file target package:
+
+```shell
+composer require yiisoft/log-target-file
+```
+
+In your application's `config/common/di/logger.php`, replace the `StreamTarget` reference with `FileTarget`:
 
+```php
+use Psr\Log\LoggerInterface;
+use Yiisoft\Definitions\ReferencesArray;
+use Yiisoft\Log\Logger;
+use Yiisoft\Log\Target\File\FileTarget;
+
+return [
+    LoggerInterface::class => [
+        'class' => Logger::class,
+        '__construct()' => [
+            'targets' => ReferencesArray::from([
+                FileTarget::class,
+            ]),
+        ],
+    ],
+];
+```
+
+The package's default configuration writes to `@runtime/logs/app.log` and enables log rotation.
+To change the path, set `$params['yiisoft/log-target-file']['fileTarget']['file']` in `config/common/params.php`.
+Ensure that the PHP process can write to the log directory, and keep it outside the web server's document root.
+
+The file target package's default configuration also filters out `alert`, `critical`, and `notice` messages.
+The templates' `StreamTarget` accepts all eight log levels. To keep that behavior, add the following entry to the
+array that `config/common/params.php` returns:
+
+```php
+use Psr\Log\LogLevel;
+
+return [
+    // Other application parameters...
+    'yiisoft/log-target-file' => [
+        'fileTarget' => [
+            'levels' => [
+                LogLevel::EMERGENCY,
+                LogLevel::ALERT,
+                LogLevel::CRITICAL,
+                LogLevel::ERROR,
+                LogLevel::WARNING,
+                LogLevel::NOTICE,
+                LogLevel::INFO,
+                LogLevel::DEBUG,
+            ],
+        ],
+    ],
+];
+```
+
+In the following, we will describe the features common to all log targets.
 
 ### Message Filtering