[DOCS] APM Example: Adds APM integration example

Author: picandocodigo

examples/apm/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org' do
+  gem 'elastic-apm'
+  gem 'elasticsearch'
+  gem 'sinatra'
+end

examples/apm/README.md

@@ -0,0 +1,47 @@
+# Observability Example
+
+This example provides a `docker-compose` file based on the [Quick start development environment](https://www.elastic.co/guide/en/apm/get-started/current/quick-start-overview.html) for APM. It gets the default distributions of Elasticsearch, Kibana and APM Server up and running in Docker.
+
+The docker-compose file also includes a basic Sinatra App and a script to ping the web app with different endpoints.
+
+Run `docker-compose up` on the root folder of this example and you'll get everything set up. Follow the steps on the full documentation [at elastic.co](https://www.elastic.co/guide/en/apm/get-started/current/quick-start-overview.html) to get APM set up in your Kibana instance.
+
+[Install Docker Compose](https://docs.docker.com/compose/install/), cd into this directory and run it:
+
+```bash
+$ cd docs/examples/apm
+$ docker-compose up
+```
+
+The following services will be available:
+
+- Kibana:              http: //localhost:5061
+- Elasticsearch:       http: //localhost:9200
+- APM Server:          http: //localhost:8200
+- Example Sinatra app: http: //localhost:9292
+
+Use your web browser or `curl` against http://localhost:9292/ to check that everything is working. You should see a JSON response from `cluster.health`.
+
+The docker-compose file will also run a `pinger` script. This script will make requests irregularly to the web app to simulate proper traffic and fill your APM Dashboard with data, even errors. You can comment the pinger container from `docker-compose.yml` if you want to have all the services running and test the different endpoints (or add your own) by yourself.
+
+# Screenshot
+
+![Kibana APM Dashboard](screenshot.jpg)
+
+# Routes in the example Sinatra app
+
+Once the app is running, you can open the following routes in your web browser or via `curl`. The responses are in JSON:
+
+* `/` - The root path returns the response from `cluster.health`
+* `/ingest` - This will bulk insert 1,000 documents in the `games` index in slices of 250 at a time.
+* `/search/{param}` - Returns search results for `param`.
+* `/error` - This route will trigger an error.
+* `/delete` - This route will delete all the data in the `games` index.
+* `/delete/{id}` - This route will delete a document with the given id from the `games` index.
+* `/update/` - This route will update the `modified` field on some docs in the `games` index.
+* `/doc/{id}` - This route will return a document with a given ID from Elasticsearch.
+
+# Data Source
+
+Data is based on a DB dump from February 25, 2020 of [TheGamesDB](https://thegamesdb.net/) game data:  
+https://cdn.thegamesdb.net/json/database-latest.json

examples/apm/config.ru

@@ -0,0 +1,8 @@
+require 'elastic-apm'
+require_relative './elastic_sinatra_app.rb'
+
+ElasticAPM.start(app: ElasticSinatraApp)
+
+run ElasticSinatraApp
+
+at_exit { ElasticAPM.stop }

examples/apm/config/elastic_apm.yml

@@ -0,0 +1,10 @@
+# Set service name - allowed characters: a-z, A-Z, 0-9, -, _ and space
+# Defaults to the name of your Rack app's class.
+service_name: 'ruby-client-apm'
+
+# Use if APM Server requires a token
+# secret_token: ''
+
+# Set custom APM Server URL (default: http://localhost:8200)
+# In this example, we're using the URL from the docker-compose apm-server instance
+server_url: 'http://apm-server:8200'

examples/apm/docker-compose.yml

@@ -0,0 +1,103 @@
+version: '2.2'
+services:
+  apm-server:
+    image: docker.elastic.co/apm/apm-server:7.6.2
+    depends_on:
+      elasticsearch:
+        condition: service_healthy
+      kibana:
+        condition: service_healthy
+    cap_add: ["CHOWN", "DAC_OVERRIDE", "SETGID", "SETUID"]
+    cap_drop: ["ALL"]
+    ports:
+    - 8200:8200
+    networks:
+    - elastic
+    command: >
+       apm-server -e
+         -E apm-server.rum.enabled=true
+         -E setup.kibana.host=kibana:5601
+         -E setup.template.settings.index.number_of_replicas=0
+         -E apm-server.kibana.enabled=true
+         -E apm-server.kibana.host=kibana:5601
+         -E output.elasticsearch.hosts=["elasticsearch:9200"]
+    healthcheck:
+      interval: 30s
+      retries: 12
+      test: curl --write-out 'HTTP %{http_code}' --fail --silent --output /dev/null http://localhost:8200/
+
+  elasticsearch:
+    image: docker.elastic.co/elasticsearch/elasticsearch:7.6.2
+    environment:
+    - bootstrap.memory_lock=true
+    - cluster.name=docker-cluster
+    - cluster.routing.allocation.disk.threshold_enabled=false
+    - discovery.type=single-node
+    - ES_JAVA_OPTS=-XX:UseAVX=2 -Xms1g -Xmx1g
+    ulimits:
+      memlock:
+        hard: -1
+        soft: -1
+    volumes:
+    - esdata:/usr/share/elasticsearch/data
+    ports:
+    - 9200:9200
+    networks:
+    - elastic
+    healthcheck:
+      interval: 30s
+      retries: 10
+      test: curl -s http://localhost:9200/_cluster/health | grep -vq '"status":"red"'
+
+  kibana:
+    image: docker.elastic.co/kibana/kibana:7.6.2
+    depends_on:
+      elasticsearch:
+        condition: service_healthy
+    environment:
+      ELASTICSEARCH_URL: http://elasticsearch:9200
+      ELASTICSEARCH_HOSTS: http://elasticsearch:9200
+    ports:
+    - 5601:5601
+    networks:
+    - elastic
+    healthcheck:
+      interval: 30s
+      retries: 20
+      test: curl --write-out 'HTTP %{http_code}' --fail --silent --output /dev/null http://localhost:5601/api/status
+
+  ruby_app:
+    container_name: ruby_app
+    build:
+      dockerfile: ${PWD}/dockerfiles/ruby/Dockerfile
+      context: ${PWD}
+    depends_on:
+      - apm-server
+    environment:
+      ELASTICSEARCH_HOSTS: http://elasticsearch:9200
+    ports:
+    - 9292:9292
+    networks:
+    - elastic
+    healthcheck:
+      interval: 30s
+      retries: 20
+      test: curl --write-out 'HTTP %{http_code}' --fail --silent --output /dev/null http://localhost:9292/
+
+  pinger:
+    container_name: pinger
+    build:
+      dockerfile: ${PWD}/dockerfiles/pinger/Dockerfile
+      context: ${PWD}
+    depends_on:
+      - ruby_app
+    networks:
+    - elastic
+
+volumes:
+  esdata:
+    driver: local
+
+networks:
+  elastic:
+    driver: bridge

examples/apm/dockerfiles/pinger/Dockerfile

@@ -0,0 +1,7 @@
+From ruby:2.7
+
+WORKDIR /usr/src/app
+
+COPY ./pinger.rb .
+
+CMD ruby pinger.rb

examples/apm/dockerfiles/ruby/Dockerfile

@@ -0,0 +1,12 @@
+From ruby:2.7
+
+RUN bundle config --global frozen 1
+
+WORKDIR /usr/src/app
+
+COPY . .
+RUN bundle install
+
+EXPOSE 9292
+
+CMD RACK_ENV=production bundle exec rackup -p 9292 --host 0.0.0.0 config.ru

examples/apm/elastic_sinatra_app.rb

@@ -0,0 +1,116 @@
+require 'sinatra'
+require 'json'
+require 'elasticsearch'
+require_relative './games_data.rb'
+
+class ElasticSinatraApp < Sinatra::Base
+  use ElasticAPM::Middleware
+
+  before do
+    @client = Elasticsearch::Client.new(
+      hosts: ENV['ELASTICSEARCH_HOSTS'] || 'localhost:9200'
+    )
+  end
+
+  get '/' do
+    response = @client.cluster.health
+    json_response(response)
+  end
+
+  get '/ingest' do
+    unless @client.indices.exists(index: 'games')
+      @client.indices.create(index: 'games')
+    end
+
+    ElasticAPMExample::GAMES.each_slice(250) do |slice|
+      @client.bulk(
+        body: slice.map do |game|
+          { index: { _index: 'games', data: game } }
+        end
+      )
+    end
+    json_response(status: 'ok')
+  end
+
+  get '/search/:query' do
+    query = sanitize(params[:query])
+    response = search_elasticsearch(query)
+    json_response(response['hits']['hits'])
+  end
+
+  get '/delete' do
+    response = @client.delete_by_query(
+      index: 'games',
+      body: {
+        query: { match_all: {} }
+      }
+    )
+    json_response(response)
+  end
+
+  get '/delete/:id' do
+    id = sanitize(params[:id])
+
+    begin
+      response = @client.delete(index: 'games', id: id)
+      json_response(response)
+    rescue Elasticsearch::Transport::Transport::Errors::NotFound => e
+      json_response(e, 404)
+    end
+  end
+
+  get '/update' do
+    response = []
+    docs = search_elasticsearch
+
+    docs['hits']['hits'].each do |doc|
+      response << @client.update(
+        index: 'games',
+        id: doc['_id'],
+        body: {
+          doc: {
+            modified: DateTime.now
+          }
+        }
+      )
+    end
+    json_response(response)
+  end
+
+  get '/error' do
+    begin
+      @client.delete(index: 'games', id: 'somerandomid')
+    rescue Elasticsearch::Transport::Transport::Errors::NotFound => e
+      json_response(e, 404)
+    end
+  end
+
+  get '/doc/:id' do
+    response = @client.get(index: 'games', id: sanitize(params[:id]))
+    json_response(response)
+  end
+
+  private
+
+  def json_response(response, code = 200)
+    [
+      code,
+      { 'Content-Type' => 'application/json' },
+      [response.to_json]
+    ]
+  end
+
+  def sanitize(params)
+    Rack::Utils.escape_html(params)
+  end
+
+  def search_elasticsearch(query = '')
+    @client.search(
+      index: 'games',
+      body:
+        {
+          query: { multi_match: { query: query } }
+        }
+    )
+  end
+end