Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 40 Next »

The Essentials

With Logsene, we expose the Elasticsearch API so you can:

When you use the API, here are the things you need to know:

  • host name: logsene-receiver.sematext.com
  • port: 80 or 443 (depending on whether you want to use plain HTTP or HTTPS)
  • index name: your Logsene application token - note: this token should be kept secret (n.b. you can have N Logsene Apps, each with its own token)

Indexing

With the same REST API, you can index logs directly from your application, or you can craft your own "log sender". 

NOTE:
If you are sending logs from your application use the Elasticsearch HTTP API. If you are sending logs from a Java application use a library like log4j2-elasticsearch-http or Jest instead of Elasticsearch TransportClient.


Besides specifying your Logsene app token as the index name, it's nice to have a field named "@timestamp".  Its value should be a valid ISO 8601 timestamp. This will be used for searching and sorting when/if you use Kibana with Logsene. If you don't provide a timestamp, Logsene will add one when it receives your message.

For example, you can send a log like this:

NOW=`date "+%Y-%m-%dT%H:%M:%S"`
curl -XPOST https://logsene-receiver.sematext.com/$YOUR_TOKEN_HERE/mytype/ -d '
{
  "@timestamp": "'$NOW'",
  "message": "Hello World!"
}'

This will index a simple "hello world" message to Logsene. That event would have the current timestamp and will go to your Logsene app (provided that the $YOUR_TOKEN_HERE variable contains your token), within a type named "mytype". The type is a logical division of events. Typically, you'd put events with different structures in different types. For example, syslog messages in a type called "syslog", apache logs in a type called "apache". Essentially, the type can be anything, it's the token of your application that has to match.

For performance reasons, we highly recommend using the Bulk API, because it allows you to send multiple events with a single request. For example, the following request sends three events:

NOW=`date "+%Y-%m-%dT%H:%M:%S"`

echo '{ "index" : { "_index": "LOGSENE_APP_TOKEN_GOES_HERE", "_type" : "mytype" } }
{ "@timestamp": "'$NOW'", "severity_numeric" : 1 }
{ "index" : { "_index": "LOGSENE_APP_TOKEN_GOES_HERE", "_type" : "mytype" } }
{ "@timestamp": "'$NOW'", "message" : "hello again" }
{ "index" : { "_index": "LOGSENE_APP_TOKEN_GOES_HERE", "_type" : "mytype" } }
{ "@timestamp": "'$NOW'", "alternate_message": "fields can be added and removed at will" }' > req

curl -XPOST https://logsene-receiver.sematext.com/_bulk --data-binary @req; echo

Default Log Index Mapping

A mapping is a way to define how your logs are indexed - which fields are in each log event and how each field is indexed. Logsene provides a default mapping that works well for most use-cases:

  • the @timestamp field is an ISO 8601 date
  • the geoip field is an object that contains a location geo point field (this works well if you're using Logstash)
  • the predefined fields host, facility, severity, syslog-tag, source and tags are not analyzed, which enables only exact matches (you can still use wildcards, for example to search for web-server* and get web-server01)
  • all string fields are analyzed by whitespace and lowercased by default, enabling a search for message:hello to match an event with Hello World in the message field

Modifying Default Log Index Mapping

If you need to define specific fields manually, you can use the Put Mapping API, where you specify logsene-receiver.sematext.com as the host name, 80/443 as the port, and your Logsene application token as the index name.  See Custom Logsene Mapping Template How To.

For example, let's assume you have a type called userlogs, where your logs have a float field called price. To define it upfront, you can run the following command (replacing $TOKEN with your Logsene app token):

curl -XPUT "https://logsene-receiver.sematext.com/$TOKEN/userlogs/_mapping" -d'
{
    "user-logs": {
        "properties": {
            "price": {
                "type": "float"
            }
        }
    }
}'

NOTE: if you already have a mapping in place, please note that some changes may not be compatible and should not be done.  For example, changing a field from float to integer won't be allowed.  If you already have data for some field and you change its mapping in an incompatible way, it needs to be re-indexed with new mapping settings. There are two options to handle this:

  1. Create a new Logsene app with new mapping and start shipping your logs there instead
  2. Remove the old mapping - which also remove all logs from the type - and retry putting the new mapping. Here's an example of removing a mapping:
     
curl -XDELETE "https://logsene-receiver.sematext.com/$TOKEN/userlogs"

Adding new fields doesn't require mapping deletion or reindexing.  Removing fields also doesn't require reindexing.  Of course, logs that have the removed fields should not be sent to Logsene after that.

Custom Log Index Mapping

See Custom Logsene Mapping Template How To.

  • No labels