Logstash is an open-source log aggregation, transformation tool, and server-side data processing pipeline that simultaneously ingests data from many sources. With Logstash, you can collect, parse, send, and store logs for future use on Axiom.

Logstash works as a data pipeline tool with Axiom, where, from one end, the data is input from your servers and system and, from the other end, Axiom takes out the data and converts it into useful information.

It can read data from various input sources, filter data for the specified configuration, and eventually store it.

Logstash sits between your data and where you want to keep it.

​
Prerequisites

​
Configuration

To configure the logstash.conf file, define the source, set the rules to format your data, and set Axiom as the destination where the data is sent.

The Logstash configuration works with OpenSearch, so you can use the OpenSearch syntax to define the source and destination.

The Logstash Pipeline has three stages:

  • Input stage generates the event & Ingest Data of all volumes, Sizes, forms, and Sources
  • Filter stage modifies the event as you specify in the filter component
  • Output stage shifts and sends the event into Axiom.

​
OpenSearch output

For installation instructions for the plugin, check out the OpenSearch documentation

In logstash.conf, configure your Logstash pipeline to collect and send data logs to Axiom.

The example below shows Logstash configuration that sends data to Axiom:

input{
  exec{
    command => "date"
    interval => "1"
  }
}
output{
  opensearch{
    hosts => ["https://AXIOM_DOMAIN:443/v1/datasets/DATASET_NAME/elastic"]
    user => "axiom"
    password => "API_TOKEN"
  }
}

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

​
Combining filters with conditionals on Logstash events

Logstash provides an extensive array of filters that allow you to enhance, manipulate, and transform your data. These filters can be used to perform tasks such as extracting, removing, and adding new fields and changing the content of fields.

Some valuable filters include the following.

​
Grok filter plugin

The Grok filter plugin allows you to parse the unstructured log data into something structured and queryable, and eventually send the structured logs to Axiom. It matches the unstructured data to patterns and maps the data to specified fields.

Here’s an example of how to use the Grok plugin:

input{
  exec{
    command => "axiom"
    interval => "1"
  }
}

filter {
  grok {
    match => { "message" => "%{COMBINEDAPACHELOG}" }
  }

  date {
    match => [ "timestamp" , "dd/MMM/yyyy:HH:mm:ss Z" ]
  }

  mutate {
    add_field => { "foo" => "Hello Axiom, from Logstash" }
    remove_field => [ "axiom", "logging" ]
  }
}

output{
  opensearch{
    hosts => ["https://AXIOM_DOMAIN:443/v1/datasets/DATASET_NAME/elastic"]
    user => "axiom"
    password => "API_TOKEN"
  }
}

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

This configuration parses Apache log data by matching the pattern of COMBINEDAPACHELOG.

​
Mutate filter plugin

The Mutate filter plugin allows you to perform general transformations on fields. For example, rename, convert, strip, and modify fields in event data.

Here’s an example of using the Mutate plugin:

input{
  exec{
    command => "axiom"
    interval => "1"
  }
}

filter {
  mutate {
    rename => { "hostname" => "host" }
    convert => { "response" => "integer" }
    uppercase => [ "method" ]
    remove_field => [ "request", "httpversion" ]
  }
}

output{
  opensearch{
    hosts => ["https://AXIOM_DOMAIN:443/v1/datasets/DATASET_NAME/elastic"]
    user => "axiom"
    password => "API_TOKEN"
  }
}

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

This configuration renames the field hostname to host, converts the response field value to an integer, changes the method field to uppercase, and removes the request and httpversion fields.

​
Drop filter plugin

The Drop filter plugin allows you to drop certain events based on specified conditions. This helps you to filter out unnecessary data.

Here’s an example of using the Drop plugin:

input {
  syslog {
    port => 5140
    type => syslog
  }
}

filter {
  if [type] == "syslog" and [severity] == "debug" {
    drop { }
  }
}

output{
  opensearch{
    hosts => ["https://AXIOM_DOMAIN:443/v1/datasets/DATASET_NAME/elastic"]
    user => "axiom"
    password => "API_TOKEN"
  }
}

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

This configuration drops all events of type syslog with severity debug.

​
Clone filter plugin

The Clone filter plugin creates a copy of an event and stores it in a new event. The event continues along the pipeline until it ends or is dropped.

Here’s an example of using the Clone plugin:

input {
  syslog {
    port => 5140
    type => syslog
  }
}

filter {
  clone {
    clones => ["cloned_event"]
  }
}

output{
  opensearch{
    hosts => ["https://AXIOM_DOMAIN:443/v1/datasets/DATASET_NAME/elastic"]
    user => "axiom"
    password => "API_TOKEN"
  }
}

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

This configuration creates a new event named cloned_event that is a clone of the original event.

​
GeoIP filter plugin

The GeoIP filter plugin adds information about the geographical location of IP addresses. This data includes the latitude, longitude, continent, country, and so on.

Here’s an example of using the GeoIP plugin:

input{
  exec{
    command => "axiom"
    interval => "6"
  }
}

filter {
  geoip {
    source => "ip"
  }
}

output{
  opensearch{
    hosts => ["https://AXIOM_DOMAIN:443/v1/datasets/DATASET_NAME/elastic"]
    user => "axiom"
    password => "API_TOKEN"
  }
}

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

This configuration adds geographical location data for the IP address in the ip field. Note that you may need to specify the path to the GeoIP database file in the plugin configuration, depending on your setup.