ECS and Docker instructions

Author: mwunderl

doc-source/index.md

@@ -35,6 +35,7 @@ Amazon's trademarks and trade dress may not be used in
    + [Instrumenting Outgoing HTTP Calls](scorekeep-httpclient.md)
    + [Instrumenting Calls to a PostgreSQL Database](scorekeep-postgresql.md)
    + [Instrumenting AWS Lambda Functions](scorekeep-lambda.md)
+   + [Instrumenting Amazon ECS Applications](scorekeep-ecs.md)
    + [Instrumenting Startup Code](scorekeep-startup.md)
    + [Instrumenting Scripts](scorekeep-scripts.md)
    + [Instrumenting a Web App Client](scorekeep-client.md)

doc-source/scorekeep-ecs.md

@@ -0,0 +1,33 @@
+# Instrumenting Amazon ECS Applications<a name="scorekeep-ecs"></a>
+
+In the [https://github.com/awslabs/eb-java-scorekeep/tree/xray-ecs](https://github.com/awslabs/eb-java-scorekeep/tree/xray-ecs) branch, the Scorekeep sample application shows how to instrument an application running in Amazon Elastic Container Service \(Amazon ECS\)\. The branch provides scripts and configuration files for creating, uploading, and running Docker images in a Multicontainer Docker environment in AWS Elastic Beanstalk\.
+
+The project includes three Dockerfiles that define container images for the API, front end, and X\-Ray daemon components\.
+
++ `/Dockerfile` – The Scorekeep API\.
+
++ `/scorekeep-frontend/Dockerfile` – The Angular web app client, and the nginx proxy that routes incoming traffic\.
+
++ `/xray-daemon/Dockerfile` – The X\-Ray daemon\.
+
+The X\-Ray daemon Dockerfile creates an image based on Amazon Linux that runs the X\-Ray daemon\.
+
+**Example Dockerfile – Amazon Linux**  
+
+```
+FROM amazonlinux
+RUN yum install -y unzip
+RUN curl -o daemon.zip https://s3.dualstack.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-2.x.zip
+RUN unzip daemon.zip && cp xray /usr/bin/xray
+ENTRYPOINT ["/usr/bin/xray", "-b", "0.0.0.0:2000"]
+EXPOSE 2000/udp
+```
+
+The makefile in the same directory defines commands for building the image, uploading it to Amazon ECR, and [running it locally](xray-daemon-local.md#xray-daemon-local-docker)\.
+
+To run the containers on Amazon ECS, the branch includes a script to generate a `Dockerrun.aws.json` file, which you can deploy to a multicontainer Docker environment in Elastic Beanstalk\. The [template](https://github.com/awslabs/eb-java-scorekeep/tree/xray-ecs/task-definition/template/scorekeep-dockerrun.template) that the script uses shows how to write a task definition that configures [networking between the containers in Amazon ECS](xray-daemon-ecs.md)\. 
+
+**Note**  
+`Dockerrun.aws.json` is the Elastic Beanstalk version of an Amazon ECS task definition file\. If you don't want to use Elastic Beanstalk to create your Amazon ECS cluster, you can modify the `Dockerrun.aws.json` file to run on Amazon ECS directly by removing the `AWSEBDockerrunVersion` key from the file\.
+
+See the [branch README](https://github.com/awslabs/eb-java-scorekeep/tree/xray-ecs) for instructions on how to deploy Scorekeep to Amazon ECS\.

doc-source/scorekeep-scripts.md

@@ -8,7 +8,7 @@ You can also instrument code that isn't part of your application\. When the X\-R
 SEGMENT=$(python bin/xray_start.py)
 gradle build --quiet --stacktrace &> /var/log/gradle.log; GRADLE_RETURN=$?
 if (( GRADLE_RETURN != 0 )); then 
-  echo "Grade failed with exit status $GRADLE_RETURN" >&2
+  echo "Gradle failed with exit status $GRADLE_RETURN" >&2
   python bin/xray_error.py "$SEGMENT" "$(cat /var/log/gradle.log)"
   exit 1
 fi

doc-source/xray-api-sendingdata.md

@@ -166,7 +166,7 @@ $ cat segment.txt > /dev/udp/127.0.0.1/2000
 {"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
 ```
 
-Check the daemon log to verify that it sent the segment to X\-Ray\.
+Check the [daemon log](xray-daemon.md#xray-daemon-logging) to verify that it sent the segment to X\-Ray\.
 
 ```
 2017-07-07T01:57:24Z [Debug] processor: sending partial batch

doc-source/xray-console-deeplinks.md

@@ -63,13 +63,13 @@ https://console.aws.amazon.com/xray/home#/service-map?timeRange=PT1H
 **Example Time range accurate to seconds**  
 
 ```
-https://console.aws.amazon.com/xray/home#/traces?timeRange=2018-2-01T16:00:00~2018-2-01T22:00:00
+https://console.aws.amazon.com/xray/home#/traces?timeRange=2018-3-01T16:00:00~2018-3-01T22:00:00
 ```
 
 **Example Time range accurate to minutes**  
 
 ```
-https://console.aws.amazon.com/xray/home#/traces?timeRange=2018-2-01T16:00~2018-2-01T22:00
+https://console.aws.amazon.com/xray/home#/traces?timeRange=2018-3-01T16:00~2018-3-01T22:00
 ```
 
 ## Region<a name="xray-console-deeplinks-region"></a>

doc-source/xray-console-filters.md

@@ -184,12 +184,12 @@ Complex keywords let you find requests based on service name, edge name, or anno
 
 + `edge(name) {filter}` – Connection between services *source* and *destination*\. Optional curly braces can contain a filter expression that applies to segments on this connection\.
 
-+ `annotation.key` – Value of annotation with field *key*\. The value of an annotation can be a boolean, number, or string, so you can use any of those type's comparison operators\.
++ `annotation.key` – Value of annotation with field *key*\. The value of an annotation can be a boolean, number, or string, so you can use any of those type's comparison operators\. You cannot use this keyword in combination with the `service` or `edge` keywords\.
 
 Use the service keyword to find traces for requests that hit a certain node on your service map\.
 
 **Example Service filter**  
-Requests that included a call to "api\.example\.com" with a fault \(500 series error\)\.  
+Requests that included a call to `api.example.com` with a fault \(500 series error\)\.  
 
 ```
 service("api.example.com") { fault }
@@ -207,7 +207,7 @@ service() { fault }
 The edge keyword applies a filter expression to a connection between two nodes\.
 
 **Example Edge filter**  
-Request where the service "api\.example\.com" made a call to "backend\.example\.com" that failed with an error\.  
+Request where the service `api.example.com` made a call to `backend.example.com` that failed with an error\.  
 
 ```
 edge("api.example.com", "backend.example.com") { error }
@@ -216,7 +216,7 @@ edge("api.example.com", "backend.example.com") { error }
 You can also use the `!` operator with service and edge keywords to exclude a service or edge from the results of another filter expression\.
 
 **Example Service and request filter**  
-Request where the URL begins with "http://api\.example\.com/" and contains "/v2/" but does not reach a service named "api\.example\.com"\.  
+Request where the URL begins with `http://api.example.com/` and contains `/v2/` but does not reach a service named `api.example.com`\.  
 
 ```
 http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")
@@ -225,28 +225,28 @@ http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !
 For annotations, use the comparison operators that correspond to the type of value\.
 
 **Example Annotation with string value**  
-Requests that caused a fault anywhere on your service map\.  
+Requests with an annotation named `gameid` with string value `"817DL6VO"`\.  
 
 ```
 annotation.gameid = "817DL6VO"
 ```
 
 **Example Annotation with number value**  
-Requests that caused a fault anywhere on your service map\.  
+Requests with annotation age with numerical value greater than 29\.  
 
 ```
 annotation.age > 29
 ```
 
 ## The ID Function<a name="console-filters-functions"></a>
 
-When you provide a service name to the service\(\) or edge\(\) keywords, you get results for all nodes that have that name\. For more precise filtering, you can use the id\(\) function to specify a service type in addition to a name to distinguish between nodes with the same name\.
+When you provide a service name to the `service` or `edge` keywords, you get results for all nodes that have that name\. For more precise filtering, you can use the `id` function to specify a service type in addition to a name to distinguish between nodes with the same name\.
 
 ```
 id(name: "service-name", type:"service::type")
 ```
 
-You can use the id\(\) function in place of a service name in service and edge filters\.
+You can use the `id` function in place of a service name in service and edge filters\.
 
 ```
 service(id(name: "service-name", type:"service::type")) { filter }
@@ -263,16 +263,16 @@ For example, the [Scorekeep sample application](xray-scorekeep.md) includes an A
 The two nodes have the same name but different types\. A standard service filter will find traces for both\.
 
 **Example Service filter**  
-Requests that include an error on any service named "random\-name"\.  
+Requests that include an error on any service named `random-name`\.  
 
 ```
 service("random-name") { error }
 ```
 
-Use the id\(\) function to narrow the search down to errors on the function itself, excluding errors from the service\.
+Use the `id` function to narrow the search down to errors on the function itself, excluding errors from the service\.
 
-**Example Service filter with id\(\) function**  
-Requests that include an error on a service named "random\-name" with type "AWS::Lambda::Function"\.  
+**Example Service filter with id function**  
+Requests that include an error on a service named `random-name` with type `AWS::Lambda::Function`\.  
 
 ```
 service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }
@@ -281,7 +281,7 @@ service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }
 You can also exclude the name entirely, to search for nodes by type\.
 
 **Example Service filter with id\(\) function**  
-Requests that include an error on a service with type "AWS::Lambda::Function"\.  
+Requests that include an error on a service with type `AWS::Lambda::Function`\.  
 
 ```
 service(id(type: "AWS::Lambda::Function")) { error }

doc-source/xray-daemon-beanstalk.md

@@ -1,19 +1,17 @@
 # Running the X\-Ray Daemon on AWS Elastic Beanstalk<a name="xray-daemon-beanstalk"></a>
 
-You can run the X\-Ray daemon on your Elastic Beanstalk environment's EC2 instances to relay trace data from your application to AWS X\-Ray\.
+To relay trace data from your application to AWS X\-Ray, you can run the X\-Ray daemon on your Elastic Beanstalk environment's Amazon EC2 instances\. For a list of supported platforms, see [Configuring AWS X\-Ray Debugging](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environment-configuration-debugging.html) in the *AWS Elastic Beanstalk Developer Guide*\.
 
 **Note**  
-For a list of supported platforms, see [Configuring AWS X\-Ray Debugging](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environment-configuration-debugging.html) in the AWS Elastic Beanstalk Developer Guide\.
-
 The daemon uses your environment's instance profile for permissions\. For instructions about adding permissions to the Elastic Beanstalk instance profile, see [Giving the Daemon Permission to Send Data to X\-Ray](xray-daemon.md#xray-daemon-permissions)\.
 
-AWS Elastic Beanstalk platforms provide a configuration option that you can set to run the daemon automatically\. You can enable the daemon in a configuration file in your source code or by checking an option in the Elastic Beanstalk console\.
+Elastic Beanstalk platforms provide a configuration option that you can set to run the daemon automatically\. You can enable the daemon in a configuration file in your source code or by choosing an option in the Elastic Beanstalk console\. When you enable the configuration option, the daemon is installed on the instance and runs as a service\.
 
-The daemon is installed on the instance and runs as a service when you enable the configuration option\.
+The version included on Elastic Beanstalk platforms might not be the latest version\. See the [Supported Platforms topic](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/concepts.platforms.html) to find out the version of the daemon that is available for your platform configuration\.
 
-The version included on Elastic Beanstalk platforms may not be the latest version\. See the Elastic Beanstalk release notes to find out the version of the daemon that is available for the platform configuration that you use\.
+Elastic Beanstalk does not provide the X\-Ray daemon on the Multicontainer Docker \(Amazon ECS\) platform\. The Scorekeep sample application shows how to use the X\-Ray daemon on Amazon ECS with Elastic Beanstalk\. See [Instrumenting Amazon ECS Applications](scorekeep-ecs.md) for details\.
 
-## Using Elastic Beanstalk's X\-Ray Integration to Run the X\-Ray Daemon<a name="xray-daemon-beanstalk-option"></a>
+## Using the Elastic Beanstalk X\-Ray Integration to Run the X\-Ray Daemon<a name="xray-daemon-beanstalk-option"></a>
 
 Use the console to turn on X\-Ray integration, or configure it in your application source code with a configuration file\.
 
@@ -47,7 +45,7 @@ Elastic Beanstalk passes a configuration file to the daemon and outputs logs to
 
 + **Configuration file** – `C:\Progam Files\Amazon\XRay\cfg.yaml`
 
-+ **Logs** – `c:\Progam Files\Amazon\XRay\logs\xray-service.log`
++ **Logs** – `c:\Program Files\Amazon\XRay\logs\xray-service.log`
 
 **On Linux Platforms**
 
@@ -164,4 +162,4 @@ files:
       C:\Program Files\Amazon\XRay\xray-daemon.log
 ```
 
-These examples also adds the daemon's log file to Elastic Beanstalk's tail logs task, to include it when you request logs with the console or Elastic Beanstalk Command Line Interface \(EB CLI\)\.
+These examples also add the daemon's log file to the Elastic Beanstalk tail logs task, so that it's included when you request logs with the console or Elastic Beanstalk Command Line Interface \(EB CLI\)\.

doc-source/xray-daemon-configuration.md

@@ -1,6 +1,22 @@
 # Configuring the AWS X\-Ray Daemon<a name="xray-daemon-configuration"></a>
 
-You can use command line options or a configuration file to customize the X\-Ray daemon's behavior\.
+You can use command line options or a configuration file to customize the X\-Ray daemon's behavior\. Most options are available using both methods, but some are only available in configuration files and some only at the command line\.
+
+To get started, the only option that you need to know is `-n` or `--region`, which you use to set the region that the daemon uses to send trace data to X\-Ray\.
+
+```
+~/xray-daemon$ ./xray -n us-east-2
+```
+
+If you are running the daemon locally, that is, not on Amazon EC2, you can add the `-o` option to skip checking for instance profile credentials so the daemon will become ready more quickly\.
+
+```
+~/xray-daemon$ ./xray -o -n us-east-2
+```
+
+The rest of the command line options let you configure logging, listen on a different port, limit the amount of memory that the daemon can use, or assume a role to send trace data to a different account\.
+
+You can pass a configuration file to the daemon to access advanced configuration options and do things like limit the number of concurrent calls to X\-Ray, disable log rotation, and send traffic to a proxy\.
 
 
 + [Using Command Line Options](#xray-daemon-configuration-commandline)
@@ -106,9 +122,8 @@ You can also use a YAML format file to configure the daemon\. Pass the configura
 
 + `Version` – Daemon configuration file format version\.
 
-The following configuration file changes the daemon's listening port to 3000, turns off checks for instance metadata, sets a role to use for uploading segments, and changes region and logging options\.
-
 **Example xray\-daemon\.yaml**  
+This configuration file changes the daemon's listening port to 3000, turns off checks for instance metadata, sets a role to use for uploading segments, and changes region and logging options\.  
 
 ```
 Socket: