{"user":"nmhung1210","name":"nginx-alpine-amplify","namespace":"nmhung1210","repository_type":"image","status":1,"status_description":"active","description":"Docker Nginx Alpine Image with Amplify monitor","is_private":false,"is_automated":true,"star_count":1,"pull_count":793,"last_updated":"2018-03-14T17:13:19.298145Z","last_modified":"2024-10-16T13:48:34.145251Z","date_registered":"2017-11-02T13:47:24.717748Z","collaborator_count":0,"affiliation":null,"hub_user":"nmhung1210","has_starred":false,"full_description":"\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n [![Docker Stars](https://img.shields.io/docker/stars/nmhung1210/nginx-alpine-amplify.svg?style=plastic)](https://registry.hub.docker.com/v2/repositories/nmhung1210/nginx-alpine-amplify/stars/count/) [![Docker pulls](https://img.shields.io/docker/pulls/nmhung1210/nginx-alpine-amplify.svg?style=plastic)](https://registry.hub.docker.com/v2/repositories/nmhung1210/nginx-alpine-amplify/)\n[![Docker Automated build](https://img.shields.io/docker/automated/nmhung1210/nginx-alpine-amplify.svg?maxAge=2592000?style=plastic)](https://github.com/nmhung1210/nginx-alpine-amplify/)\n\n- [1. Overview](#1-overview)\n  - [1.1. NGINX Amplify Agent Inside Docker Container](#11-nginx-amplify-agent-inside-docker-container)\n  - [1.2. Standalone Mode](#12-standalone-mode)\n  - [1.3. Aggregate Mode](#13-aggregate-mode)\n  - [1.4. Current Limitations](#14-current-limitations)\n- [2. How to Build and Run an Amplify-enabled NGINX image?](#2-how-to-build-and-run-an-amplify-enabled-nginx-image)\n  - [2.1. Building an Amplify-enabled image with NGINX](#21-building-an-amplify-enabled-image-with-nginx)\n  - [2.2. Running an Amplify-enabled NGINX Docker Container](#22-running-an-amplify-enabled-nginx-docker-container)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\n## 1. Overview\n\n[NGINX Amplify](https://amplify.nginx.com/signup/) is a free monitoring tool that can be used with a microservice architecture based on NGINX and Docker. Amplify is developed and maintained by Nginx Inc. — the company behind the NGINX software.\n\nWith Amplify it is possible to collect and aggregate metrics across Docker containers, and present a coherent set of visualizations of the key NGINX performance data, such as active connections or requests per second. It is also easy to quickly check for any performance degradations, traffic anomalies, and get a deeper insight into the NGINX configuration in general.\n\nIn order to use Amplify, a small Python-based agent software [Amplify Agent](https://github.com/nginxinc/nginx-amplify-agent) should be installed inside the container.\n\nThe official documentation for Amplify is available [here](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-guide.md).\n\n### 1.1. NGINX Amplify Agent Inside Docker Container \n\nThe Amplify Agent can be deployed in a Docker environment to monitor NGINX instances inside Docker containers.\n\nThe \"agent-inside-the-container\" is currenly the only mode of operation. In other words, the agent should be running in the same container, next to the NGINX instance.\n\n### 1.2. Standalone Mode\n\nBy default the agent will try to determine the OS `hostname` on startup (see the docs [here](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-guide.md#changing-the-hostname-and-uuid) for more information). The `hostname` is used to generate an UUID to uniquely identify the new object in the monitoring backend.\n\nThis means that in the absence of the additional configuration steps, each new container started from an Amplify-enabled Docker image will be reported as a standalone system in the Amplify web user interface. Moreover, the reported hostname is typically something not easily readable.\n\nWhen using Amplify with Docker, another option is available and recommended — which is `imagename`. The `imagename` option tells the Amplify Agent that it's running in a container environment, and that the agent should collect and report metrics and metadata accordingly.\n\nIf you prefer to see the individual instances started from the same image as separate objects, assign different `imagename` to each of the running instances.\n\nYou can learn more about the agent configuration options [here](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-guide.md#configuring-the-agent).\n\n### 1.3. Aggregate Mode\n\nAs described above, when reporting a new object for monitoring, the agent honors the `imagename` configuration option in the **/etc/amplify-agent/agent.conf** file.\n\nThe `imagename` option should be set either in the Dockerfile or using the environment variables.\n\nIt is possible to explicitly specify the same `imagename` for multiple instances. In this scenario, the metrics received from several agents will be aggregated internally on the backend side — with a single 'container'-type object created for monitoring.\n\nThis way a combined view of various statistics can be obtained (e.g. for a \"microservice\"). For example, this combined view can display the total number of requests per second through all backend instances of a microservice.\n\nContainers with a common `imagename` do not have to share the same local Docker image or NGINX configuration. They can be located on different physical hosts too.\n\nTo set a common `imagename` for several containers started from the Amplify-enabled image, you may either:\n\n  * Configure it explicitly in the Dockerfile\n  \n  ```\n  # If AMPLIFY_IMAGENAME is set, the startup wrapper script will use it to\n  # generate the 'imagename' to put in the /etc/amplify-agent/agent.conf\n  # If several instances use the same 'imagename', the metrics will\n  # be aggregated into a single object in NGINX Amplify. Otherwise Amplify\n  # will create separate objects for monitoring (an object per instance).\n  # AMPLIFY_IMAGENAME can also be passed to the instance at runtime as\n  # described below.\n  \n  ENV AMPLIFY_IMAGENAME my-docker-instance-123\n  ```\n\n  or\n\n  * Use the `-e` option with `docker run` as in\n\n  ```\n  docker run --name mynginx1 -e API_KEY=ffeedd0102030405060708 -e AMPLIFY_IMAGENAME=my-service-123 -d nginx-amplify\n  ```\n\n### 1.4. Current Limitations \n\nThe following list summarizes existing limitations of monitoring Docker containers with Amplify:\n\n * In order for the agent to collect [additional NGINX metrics](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-guide.md#additional-nginx-metrics) the NGINX logs should be kept inside the container (by default the NGINX logs are redirected to the Docker log collector). Alternatively the NGINX logs can be fed to the agent via [syslog](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-guide.md#configuring-syslog).\n * In \"aggregate\" mode, some of the OS metrics and metadata are not collected (e.g. hostnames, CPU usage, Disk I/O metrics, network interface configuration).\n * The agent can only monitor NGINX from inside the container. It is not currently possible to run the agent in a separate container and monitor the neighboring containers running NGINX.\n \nWe've been working on improving the support for Docker even more. Stay tuned!\n\n## 2. How to Build and Run an Amplify-enabled NGINX image?\n\n### 2.1. Building an Amplify-enabled image with NGINX\n\n(**Note**: If you are really new to Docker, [here's](https://docs.docker.com/engine/installation/) how to install Docker Engine on various OS.)\n\nHere's how you can build the Docker Alpine image with the Amplify Agent inside, based on the official NGINX image:\n\n```\ngit clone https://github.com/nmhung1210/nginx-alpine-amplify\n```\n\n```\ncd nginx-alpine-amplify\n```\n\n```\ndocker build -t nginx-alpine-amplify .\n```\n\nAfter the image is built, check the list of Docker images:\n\n```\ndocker images\n```\n\n```\nREPOSITORY                 TAG                 IMAGE ID            CREATED             SIZE\nnginx-alpine-amplify       latest              d039b39d2987        3 minutes ago       241.6 MB\n```\n\n### 2.2. Running an Amplify-enabled NGINX Docker Container\n\nUnless already done, you have to [sign up](https://amplify.nginx.com/signup/), create an account in NGINX Amplify, and obtain a valid API_KEY.\n\nTo start a container from the new image, use the command below:\n\n```\ndocker run --name mynginx1 -e API_KEY=ffeedd0102030405060708 -e AMPLIFY_IMAGENAME=my-service-123 -d nginx-amplify\n```\n\nwhere the API_KEY is that assigned to your NGINX Amplify account, and the AMPLIFY_IMAGENAME is set to identify the running service as described in sections 1.2 and 1.3 above.\n\nAfter the container has started, you may check its status with `docker ps`:\n\n```\ndocker ps\n```\n\n```\nCONTAINER ID        IMAGE                      COMMAND             CREATED             STATUS              PORTS               NAMES\n7d7b47ba4c72        nginx-alpine-amplify       \"/entrypoint.sh\"    3 seconds ago       Up 2 seconds        80/tcp, 443/tcp     mynginx1\n```\n\nand you can also check `docker logs`:\n\n```\ndocker logs 7d7b47ba4c72\n```\n\n```\nstarting nginx ...\nupdating /etc/amplify-agent/agent.conf ...\n---\u003e using api_key = ffeedd0102030405060708\n---\u003e using imagename = my-service-123\nstarting amplify-agent ...\n```\n\nCheck what processes have started:\n\n```\ndocker exec 7d7b47ba4c72 ps axu\n```\n\n```\nUSER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND\nroot         1  0.0  0.1   4328   676 ?        Ss   19:33   0:00 /bin/sh /entrypoint.sh\nroot         5  0.0  0.5  31596  2832 ?        S    19:33   0:00 nginx: master process nginx -g daemon off;\nnginx       11  0.0  0.3  31988  1968 ?        S    19:33   0:00 nginx: worker process\nnginx       65  0.6  9.1 111584 45884 ?        S    19:33   0:06 amplify-agent\n```\n\nIf you see the **amplify-agent** process, it all went smoothly, and you should see the new container in the Amplify web user interface in about a minute or so.\n\nCheck the Amplify Agent log:\n\n```\ndocker exec 7d7b47ba4c72 tail /var/log/amplify-agent/agent.log\n```\n\n```\n2016-08-05 19:49:39,001 [65] supervisor agent started, version=0.37-1 pid=65 uuid=\u003c..\u003e imagename=my-service-123\n2016-08-05 19:49:39,047 [65] nginx_config running nginx -t -c /etc/nginx/nginx.conf\n2016-08-05 19:49:40,047 [65] supervisor post https://receiver.amplify.nginx.com:443/\u003c..\u003e/ffeedd0102030405060708/agent/ 200 85 4 0.096\n2016-08-05 19:50:24,674 [65] bridge_manager post https://receiver.amplify.nginx.com:443/\u003c..\u003e/ffeedd0102030405060708/update/ 202 2370 0 0.084\n```\n\nWhen you're done with the container, you can stop it like the following:\n\n```\ndocker stop 7d7b47ba4c72\n```\n\nTo check the status of all containers (running and stopped):\n\n```\ndocker ps -a\n```\n\n```\nCONTAINER ID     IMAGE                 COMMAND             CREATED             STATUS                        PORTS               NAMES\n7d7b47ba4c72     nginx-alpine-amplify  \"/entrypoint.sh\"    22 minutes ago      Exited (137) 19 seconds ago                       mynginx1\n```\n\nHappy monitoring, and feel free to send us questions, opinions, and any feedback in general.\n","permissions":{"read":true,"write":false,"admin":false},"media_types":["application/vnd.docker.container.image.v1+json"],"content_types":["image"],"categories":[],"immutable_tags_settings":{"enabled":false,"rules":[".*"]},"storage_size":423652704,"source":null}