You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@samza.apache.org by cr...@apache.org on 2014/08/20 20:09:52 UTC
git commit: SAMZA-381; update docs for log4j jmx appender.
Repository: incubator-samza
Updated Branches:
refs/heads/master 42df2b44f -> aef99452e
SAMZA-381; update docs for log4j jmx appender.
Project: http://git-wip-us.apache.org/repos/asf/incubator-samza/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-samza/commit/aef99452
Tree: http://git-wip-us.apache.org/repos/asf/incubator-samza/tree/aef99452
Diff: http://git-wip-us.apache.org/repos/asf/incubator-samza/diff/aef99452
Branch: refs/heads/master
Commit: aef99452ea7e3a343737d3121435dbf164301517
Parents: 42df2b4
Author: Chris Riccomini <cr...@criccomi-mn.linkedin.biz>
Authored: Wed Aug 20 11:09:46 2014 -0700
Committer: Chris Riccomini <cr...@criccomi-mn.linkedin.biz>
Committed: Wed Aug 20 11:09:46 2014 -0700
----------------------------------------------------------------------
docs/README.md | 21 ++++++-------
.../documentation/versioned/jobs/logging.md | 31 ++++++++++++++++----
2 files changed, 35 insertions(+), 17 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/aef99452/docs/README.md
----------------------------------------------------------------------
diff --git a/docs/README.md b/docs/README.md
index e31b2eb..7efbaca 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -24,30 +24,27 @@ Samza's documentation uses Jekyll to build a website out of markdown pages. Prer
To serve the website on [localhost:4000](http://localhost:4000/):
- bundle exec jekyll serve --watch
+ bundle exec jekyll serve --watch --baseurl
To compile the website in the \_site directory, execute:
bundle exec jekyll build
-To test the site,
+To test the site, run:
- * run:
+ bundle exec jekyll serve --watch --baseurl
- bundle exec jekyll serve --watch --baseurl
+## Versioning
- * then open another command line window and run:
+If you're working with versioned content (anything in the learn or img directories), you'll also need to run a script that generates the appropriate directories:
_docs/local-site-test.sh
- * keep in mind that the switch-version buttons in other versions link to samza.incubator.apache.org/,
- not the localhost:4000. That is because they are not updated by your branch and are using the value in SVN.
-
-## Versioning
+The local-site-test.sh script must be run every time a change is made to versioned content locally in order to trigger a refresh with Jekyll.
-The "learn" and "img" sections are versioned. To add a new version, change the version number in _config.yml. All links in pages should use
+Keep in mind that versioned content in older versions links to samza.incubator.apache.org, not the localhost:4000. This is because they are not updated by your branch and are using the values in SVN instead.
-{{site.version}}, not hard-coded version number.
+To add a new version, change the version number in _config.yml. All links in pages should use {{site.version}}, not hard-coded version number.
## Javadocs
@@ -59,6 +56,6 @@ To auto-generate the latest Javadocs, run:
To build and publish the website to Samza's Apache SVN repository, run:
- bin/publish-site.sh 0.7.0 "updating welcome page" criccomini
+ bin/publish-site.sh "updating welcome page" criccomini
This command will re-build the Javadocs and website, checkout https://svn.apache.org/repos/asf/incubator/samza/site/ locally, copy the site into the directory, and commit the changes.
http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/aef99452/docs/learn/documentation/versioned/jobs/logging.md
----------------------------------------------------------------------
diff --git a/docs/learn/documentation/versioned/jobs/logging.md b/docs/learn/documentation/versioned/jobs/logging.md
index 6af3d4d..6739740 100644
--- a/docs/learn/documentation/versioned/jobs/logging.md
+++ b/docs/learn/documentation/versioned/jobs/logging.md
@@ -47,7 +47,7 @@ Samza's [run-class.sh](packaging.html) script will automatically set the followi
The [run-class.sh](packaging.html) script will also set the following Java system properties:
{% highlight bash %}
--Dsamza.log.dir=$SAMZA_LOG_DIR -Dsamza.container.name=$SAMZA_CONTAINER_NAME=
+-Dsamza.log.dir=$SAMZA_LOG_DIR -Dsamza.container.name=$SAMZA_CONTAINER_NAME
{% endhighlight %}
These settings are very useful if you're using a file-based appender. For example, you can use a daily rolling appender by configuring log4j.xml like this:
@@ -64,15 +64,32 @@ These settings are very useful if you're using a file-based appender. For exampl
Setting up a file-based appender is recommended as a better alternative to using standard out. Standard out log files (see below) don't roll, and can get quite large if used for logging.
-**NOTE:** If you use the `task.opts` configuration property, the log configuration is disrupted. This is a known bug; please see [SAMZA-109](https://issues.apache.org/jira/browse/SAMZA-109) for a workaround.
+#### Changing log levels
+
+Sometimes it's desirable to change the Log4J log level from `INFO` to `DEBUG` at runtime so that a developer can enable more logging for a Samza container that's exhibiting undesirable behavior. Samza provides a Log4j class called JmxAppender, which will allow you to dynamically modify log levels at runtime. The JmxAppender class is located in the samza-log4j package, and can be turned on by first adding a runtime dependency to the samza-log4j package:
+
+{% highlight xml %}
+<dependency>
+ <groupId>org.apache.samza</groupId>
+ <artifactId>samza-log4j</artifactId>
+ <scope>runtime</scope>
+ <version>${samza.version}</version>
+</dependency>
+{% endhighlight %}
+
+And then updating your log4j.xml to include the appender:
+
+{% highlight xml %}
+<appender name="jmx" class="org.apache.samza.logging.log4j.JmxAppender" />
+{% endhighlight %}
### Log Directory
-Samza will look for the `SAMZA_LOG_DIR` environment variable when it executes. If this variable is defined, all logs will be written to this directory. If the environment variable is empty, or not defined, then Samza will use /tmp. This environment variable can also be referenced inside log4j.xml files (see above).
+Samza will look for the `SAMZA_LOG_DIR` environment variable when it executes. If this variable is defined, all logs will be written to this directory. If the environment variable is empty, or not defined, then Samza will use `$base_dir`, which is the directory one level up from Samza's [run-class.sh](packaging.html) script. This environment variable can also be referenced inside log4j.xml files (see above).
### Garbage Collection Logging
-Samza's will automatically set the following garbage collection logging setting, and will output it to `$SAMZA_LOG_DIR/gc.log`.
+Samza will automatically set the following garbage collection logging setting, and will output it to `$SAMZA_LOG_DIR/gc.log`.
{% highlight bash %}
-XX:+PrintGCDateStamps -Xloggc:$SAMZA_LOG_DIR/gc.log
@@ -80,7 +97,11 @@ Samza's will automatically set the following garbage collection logging setting,
#### Rotation
-In older versions of Java, it is impossible to have GC logs roll over based on time or size without the use of a secondary tool. This means that your GC logs will never be deleted until a Samza job ceases to run. As of [Java 6 Update 34](http://www.oracle.com/technetwork/java/javase/2col/6u34-bugfixes-1733379.html), and [Java 7 Update 2](http://www.oracle.com/technetwork/java/javase/7u2-relnotes-1394228.html), [new GC command line switches](http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6941923) have been added to support this functionality. If you are using a version of Java that supports GC log rotation, it's highly recommended that you turn it on.
+In older versions of Java, it is impossible to have GC logs roll over based on time or size without the use of a secondary tool. This means that your GC logs will never be deleted until a Samza job ceases to run. As of [Java 6 Update 34](http://www.oracle.com/technetwork/java/javase/2col/6u34-bugfixes-1733379.html), and [Java 7 Update 2](http://www.oracle.com/technetwork/java/javase/7u2-relnotes-1394228.html), [new GC command line switches](http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6941923) have been added to support this functionality. If GC log file rotation is supported by the JVM, Samza will also set:
+
+{% highlight bash %}
+-XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=10 -XX:GCLogFileSize=10241024
+{% endhighlight %}
### YARN