Быстрый старт

Это руководство поможет новичкам научиться:

Простейший способ настроить Elasticsearch — создать управляемое развертывание с помощью Elasticsearch Service на Elastic Cloud. Если вы предпочитаете управлять собственной тестовой средой, вы можете установить и запустить Elasticsearch с помощью Docker.

Вы отправляете данные и другие запросы в Elasticsearch с помощью REST API. Это позволяет взаимодействовать с Elasticsearch с помощью любого клиента, который отправляет HTTP-запросы, например, curl. Вы также можете использовать консоль Kibana для отправки запросов в Elasticsearch.

curl -X GET http://localhost:9200/

Вы добавляете данные в Elasticsearch в виде объектов JSON, называемых документами. Elasticsearch хранит эти документы в индексах, доступных для поиска.

Для данных временных рядов, таких как журналы и метрики, вы обычно добавляете документы в поток данных, состоящий из нескольких автоматически созданных индексов-оснований.

Поток данных требует шаблона индекса, который соответствует его имени. Elasticsearch использует этот шаблон для настройки индексов-оснований потока. Документы, отправленные в поток данных, должны иметь поле @timestamp.

Отправьте следующий запрос индексации, чтобы добавить одну запись журнала в поток данных logs-my_app-default. Поскольку logs-my_app-default не существует, запрос автоматически создает его с использованием встроенного шаблона индекса logs-*-*.

POST logs-my_app-default/_doc
{
  "@timestamp": "2099-05-06T16:21:15.000Z",
  "event": {
    "original": "192.0.2.42 - - [06/May/2099:16:21:15 +0000] \"GET /images/bg.jpg HTTP/1.0\" 200 24736"
  }
}

Ответ включает метаданные, которые Elasticsearch генерирует для документа:

{
  "_index": ".ds-logs-my_app-default-2099-05-06-000001",
  "_type": "_doc",
  "_id": "gl5MJXMBMk1dGnErnBW8",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

Используйте конечную точку _bulk, чтобы добавить несколько документов в одном запросе. Пакетные данные должны быть представленны в формате JSON с разделителями строк (NDJSON). Каждая строка должна заканчиваться символом новой строки (\n), включая последнюю строку.

PUT logs-my_app-default/_bulk
{ "create": { } }
{ "@timestamp": "2099-05-07T16:24:32.000Z", "event": { "original": "192.0.2.242 - - [07/May/2020:16:24:32 -0500] \"GET /images/hm_nbg.jpg HTTP/1.0\" 304 0" } }
{ "create": { } }
{ "@timestamp": "2099-05-08T16:25:42.000Z", "event": { "original": "192.0.2.255 - - [08/May/2099:16:25:42 +0000] \"GET /favicon.ico HTTP/1.0\" 200 3638" } }

Проиндексированные документы доступны для поиска практически в режиме реального времени. Следующий поиск соответствует всем записям журнала в logs-my_app-default и сортирует их по @timestamp в убывающем порядке.

GET logs-my_app-default/_search
{
  "query": {
    "match_all": { }
  },
  "sort": [
    {
      "@timestamp": "desc"
    }
  ]
}

По умолчанию раздел hits ответа включает до первых 10 документов, соответствующих поиску. _source каждого попадания содержит исходный объект JSON, отправленный во время индексации.

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 3,
      "relation": "eq"
    },
    "max_score": null,
    "hits": [
      {
        "_index": ".ds-logs-my_app-default-2099-05-06-000001",
        "_type": "_doc",
        "_id": "PdjWongB9KPnaVm2IyaL",
        "_score": null,
        "_source": {
          "@timestamp": "2099-05-08T16:25:42.000Z",
          "event": {
            "original": "192.0.2.255 - - [08/May/2099:16:25:42 +0000] \"GET /favicon.ico HTTP/1.0\" 200 3638"
          }
        },
        "sort": [
          4081940742000
        ]
      },
      ...
    ]
  }
}

Разбор всего _source является громоздким для больших документов. Чтобы исключить его из ответа, установите параметр _source в false. Вместо этого используйте параметр fields для извлечения нужных полей.

GET logs-my_app-default/_search
{
  "query": {
    "match_all": { }
  },
  "fields": [
    "@timestamp"
  ],
  "_source": false,
  "sort": [
    {
      "@timestamp": "desc"
    }
  ]
}

Ответ содержит значения fields каждого попадания в виде плоского массива.

{
  ...
  "hits": {
    ...
    "hits": [
      {
        "_index": ".ds-logs-my_app-default-2099-05-06-000001",
        "_type": "_doc",
        "_id": "PdjWongB9KPnaVm2IyaL",
        "_score": null,
        "fields": {
          "@timestamp": [
            "2099-05-08T16:25:42.000Z"
          ]
        },
        "sort": [
          4081940742000
        ]
      },
      ...
    ]
  }
}

Чтобы выполнить поиск в определенном временном или IP-диапазоне, используйте запрос range.

GET logs-my_app-default/_search
{
  "query": {
    "range": {
      "@timestamp": {
        "gte": "2099-05-05",
        "lt": "2099-05-08"
      }
    }
  },
  "fields": [
    "@timestamp"
  ],
  "_source": false,
  "sort": [
    {
      "@timestamp": "desc"
    }
  ]
}

Вы можете использовать математику дат для определения относительных временных диапазонов. Следующий запрос ищет данные за прошедшие сутки, которые не будут соответствовать ни одной записи журнала в logs-my_app-default.

GET logs-my_app-default/_search
{
  "query": {
    "range": {
      "@timestamp": {
        "gte": "now-1d/d",
        "lt": "now/d"
      }
    }
  },
  "fields": [
    "@timestamp"
  ],
  "_source": false,
  "sort": [
    {
      "@timestamp": "desc"
    }
  ]
}

Вы можете извлекать runtime fields из неструктурированного контента, такого как сообщения журналов, во время поиска.

Используйте следующий поиск для извлечения runtime поля source.ip из event.original. Чтобы включить его в ответ, добавьте source.ip к параметру fields.

GET logs-my_app-default/_search
{
  "runtime_mappings": {
    "source.ip": {
      "type": "ip",
      "script": """
        String sourceip=grok('%{IPORHOST:sourceip} .*').extract(doc[ "event.original" ].value)?.sourceip;
        if (sourceip != null) emit(sourceip);
      """
    }
  },
  "query": {
    "range": {
      "@timestamp": {
        "gte": "2099-05-05",
        "lt": "2099-05-08"
      }
    }
  },
  "fields": [
    "@timestamp",
    "source.ip"
  ],
  "_source": false,
  "sort": [
    {
      "@timestamp": "desc"
    }
  ]
}

Вы можете использовать запрос bool для объединения нескольких запросов. Следующий поиск объединяет два запроса range: один по @timestamp и один по runtime полю source.ip.

GET logs-my_app-default/_search
{
  "runtime_mappings": {
    "source.ip": {
      "type": "ip",
      "script": """
        String sourceip=grok('%{IPORHOST:sourceip} .*').extract(doc[ "event.original" ].value)?.sourceip;
        if (sourceip != null) emit(sourceip);
      """
    }
  },
  "query": {
    "bool": {
      "filter": [
        {
          "range": {
            "@timestamp": {
              "gte": "2099-05-05",
              "lt": "2099-05-08"
            }
          }
        },
        {
          "range": {
            "source.ip": {
              "gte": "192.0.2.0",
              "lte": "192.0.2.240"
            }
          }
        }
      ]
    }
  },
  "fields": [
    "@timestamp",
    "source.ip"
  ],
  "_source": false,
  "sort": [
    {
      "@timestamp": "desc"
    }
  ]
}

Используйте агрегации для суммирования данных в виде метрик, статистики или других аналитических данных.

Следующий поиск использует агрегацию для вычисления average_response_size с помощью runtime поля http.response.body.bytes. Агрегация выполняется только для документов, соответствующих query.

GET logs-my_app-default/_search
{
  "runtime_mappings": {
    "http.response.body.bytes": {
      "type": "long",
      "script": """
        String bytes=grok('%{COMMONAPACHELOG}').extract(doc[ "event.original" ].value)?.bytes;
        if (bytes != null) emit(Integer.parseInt(bytes));
      """
    }
  },
  "aggs": {
    "average_response_size":{
      "avg": {
        "field": "http.response.body.bytes"
      }
    }
  },
  "query": {
    "bool": {
      "filter": [
        {
          "range": {
            "@timestamp": {
              "gte": "2099-05-05",
              "lt": "2099-05-08"
            }
          }
        }
      ]
    }
  },
  "fields": [
    "@timestamp",
    "http.response.body.bytes"
  ],
  "_source": false,
  "sort": [
    {
      "@timestamp": "desc"
    }
  ]
}

Объект aggregations ответа содержит результаты агрегации.

{
  ...
  "aggregations" : {
    "average_response_size" : {
      "value" : 12368.0
    }
  }
}

Чтобы продолжить изучение, проиндексируйте больше данных в свой поток данных и ознакомьтесь с разделом Общие параметры поиска.

Когда вы закончите, удалите свой тестовый поток данных и его базовые индексы.

DELETE _data_stream/logs-my_app-default

Вы также можете удалить свое тестовое развертывание.