Skip to content

Commit

Permalink
DOC-4505 / https://issues.couchbase.com/browse/DOC-4505
Browse files Browse the repository at this point in the history
  • Loading branch information
@jamesnocentini
jamesnocentini committed Dec 6, 2018
1 parent ef5c229 commit d0dce21
Show file tree
Hide file tree
Showing 2 changed files with 1 addition and 188 deletions.
188 changes: 0 additions & 188 deletions modules/ROOT/pages/deployment-considerations.adoc
View file
Expand Up @@ -80,191 +80,3 @@ More detail on the configuration properties for x.509 authentication can be foun
* xref:config-properties.adoc#databases-foo_db-cacertpath[databases.$db.cacertpath]

If the **username**/**password** properties are also specified in the configuration file then Sync Gateway will use password-based authentication and also include the client certificate in the TLS handshake.

== Log Rotation

=== Built-in log rotation

By default, Sync Gateway outputs the logs to standard out with the "HTTP" log key and can also output logs to a file.
Prior to 1.4, the two main configuration options were `log` and `logFilePath` at the root of the configuration file.

[source,javascript]
----
{
"log": ["*"],
"logFilePath": "/var/log/sync_gateway/sglogfile.log"
}
----

In Couchbase Mobile 1.4, Sync Gateway can now be configured to perform log rotation in order to minimize disk space usage.

==== Log rotation configuration

The log rotation configuration is specified under the `logging` key.
The following example demonstrates where the log rotation properties reside in the configuration file.

[source,javascript]
----
{
"logging": {
"default": {
"logFilePath": "/var/log/sync_gateway/sglogfile.log",
"logKeys": ["*"],
"logLevel": "debug",
"rotation": {
"maxsize": 1,
"maxage": 30,
"maxbackups": 2,
"localtime": true
}
}
},
"databases": {
"db": {
"server": "walrus:data",
"bucket": "default",
"users": {"GUEST": {"disabled": false,"admin_channels": ["*"]}}
}
}
}
----

As shown above, the `logging` property must contain a single named logging appender called `default`.
Note that if the "logging" property is specified, it will override the top level `log` and `logFilePath` properties.

The descriptions and default values for each logging property can be found on the xref:config-properties.adoc[Sync Gateway configuration] page.

==== Example Output

If Sync Gateway is running with the configuration shown above, after a total of 3.5 MB of log data, the contents of the `/var/log/sync_gateway` directory would have 3 files because `maxsize` is set to 1 MB.

[source,bash]
----
/var/log/sync_gateway
├── sglogfile.log
├── sglogfile-2017-01-25T23-35-23.671.log
└── sglogfile-2017-01-25T22-25-39.662.log
----

==== Windows Configuration

On MS Windows `logFilePath` supports the following path formats.

[source,javascript]
----
"C:/var/tmp/sglogfile.log"
`C:\var\tmp\sglogfile.log`
`/var/tmp/sglogfile.log`
"/var/tmp/sglogfile.log"
----

Log rotation will not work if `logFilePath` is set to the path below as it is reserved for use by the Sync Gateway Windows service wrapper.

[source,bash]
----
C:\Program Files (x86)\Couchbase\var\lib\couchbase\logs\sync_gateway_error.log
----

==== Deprecation notice

The current proposal is to remove the top level `log` and `logFilePath` properties in Sync Gateway 2.0.
For users that want to migrate to the new logging config to write to a log file but do not need log rotation they should use a default logger similar to the following:

[source,javascript]
----
{
"logging": {
"default": {
"logFilePath": "/var/log/sync_gateway/sglogfile.log",
"logKeys": ["*"],
"logLevel": "debug"
}
}
}
----

=== OS log rotation

In production environments it is common to rotate log files to prevent them from taking too much disk space, and to support log file archival.

By default Sync gateway will write log statements to stderr, normally stderr is redirected to a log file by starting Sync Gateway with a command similar to the following:

[source,bash]
----
sync_gateway sync_gateway.json 2>> sg_error.log
----

On Linux the logrotate tool can be used to monitor log files and rotate them at fixed time intervals or when they reach a certain size.
Below is an example of a logrotate configuration that will rotate the Sync Gateway log file once a day or if it reaches 10M in size.

[source]
----
/home/sync_gateway/logs/*.log {
daily
rotate 1
size 10M
delaycompress
compress
notifempty
missingok
----

The log rotation is achieved by renaming the log file with an appended timestamp.
The idea is that Sync Gateway should recreate the default log file and start writing to it again.
The problem is Sync Gateway will follow the renamed file and keep writing to it until Sync gateway is restarted.
By adding the copy truncate option to the logrotate configuration, the log file will be rotated by making a copy of the log file, and then truncating the original log file to zero bytes.

[source]
----
/home/sync_gateway/logs/*.log {
daily
rotate 1
size 10M
copytruncate
delaycompress
compress
notifempty
missingok
}
----

Using this approach there is a possibility of loosing log entries between the copy and the truncate, on a busy Sync Gateway instance or when verbose logging is configured the number of lost entries could be large.

In Sync Gateway 1.1.0 a new configuration option has been added that gives Sync Gateway control over the log file rather than relying on *stderr*.
To use this option call Sync Gateway as follows:

[source,bash]
----
sync_gateway -logFilePath=sg_error.log sync_gateway.json
----

The *logFilePath* property can also be set in the configuration file at the xref:config-properties.adoc#server-configuration[server level].

If the option is not used then Sync Gateway uses the existing stderr logging behavior.
When the option is passed Sync Gateway will attempt to open and write to a log file at the path provided.
If a Sync Gateway process is sent the `SIGHUP` signal it will close the open log file and then reopen it, on Linux the `SIGHUP` signal can be manually sent using the following command:

[source,bash]
----
pkill -HUP sync_gateway
----

This command can be added to the logrotate configuration using the 'postrotate' option:

[source]
----
/home/sync_gateway/logs/*.log {
daily
rotate 1
size 10M
delaycompress
compress
notifempty
missingok
postrotate
/usr/bin/pkill -HUP sync_gateway > /dev/null
endscript
}
----

After renaming the log file logrotate will send the `SIGHUP` signal to the `sync_gateway` process, Sync Gateway will close the existing log file and open a new file at the original path, no log entries will be lost.
1 change: 1 addition & 0 deletions modules/ROOT/pages/release-notes.adoc
View file
Expand Up @@ -7,6 +7,7 @@ The following features are being deprecated and will be unsupported in an upcomi

* *Bucket shadowing* has been deprecated since 1.4 and has now become unsupported.
The recommended approach to perform operations on a bucket dedicated to Couchbase Mobile is to enable xref:shared-bucket-access.adoc[shared bucket access].
* The existing xref:2.0@logging.adoc[logging configuration] is being deprecated in favor of the new xref:logging.adoc[continuous logging configuration].
== 2.1.1

Expand Down

0 comments on commit d0dce21

Please sign in to comment.