Skip to main content

Events API

This guide provides instructions for querying event data from the zLAN indices in Elasticsearch, which is provided by the NetFoundry support stack. Refer to the Self-Hosted documentation for more information about the support stack.

Elastic Indices Overview​

Index NameDescriptionExample Fields
zfw.events*Ziti firewall usage broken down into granular dimensions such as firweall, address, port, interface, direction.zfw.source_id zfw.saddr, zfw.daddr, zfw.dport, zfw.usage.circuit.tx, zfw.usage.circuit.rx
ziti.alert*General purpose events which let administrators know there’s a potential configuration problem that may need to be fixed.event_source_type, severity, message, logs

🔍 Example Queries​

Fetch Top Talkers By Source Addresses​

Fetch the top 100 source IPs for a firewall, sorted by traffic sum. Adding the .keyword suffix is required when performing aggregation on specific fields.

⚠️ Please substitute ELASTICSEARCH_URL with the local installation URL. The default access URL for the remote access user is https://elasticsearch.ziti The URL, username and password should be provided during the OnPrem installation.

curl -k -X GET "{{ELASTICSEARCH_URL}}/zfw.events*/_search?pretty" \
     -u "yourusername:yourpassword" \
     -H 'Content-Type: application/json' -d'
{
  "aggs": {
    "zfw_source": {
      "terms": {
        "field": "zfw.source_id.keyword",
        "order": {
          "circuit_tx": "desc"
        },
        "size": 10
      },
      "aggs": {
        "saddr": {
          "terms": {
            "field": "zfw.saddr.keyword",
            "order": {
              "circuit_rx": "desc"
            },
            "size": 10
          },
          "aggs": {
            "circuit_rx": {
              "sum": {
                "field": "zfw.usage.circuit.rx"
              }
            }
          }
        },
        "circuit_tx": {
          "sum": {
            "field": "zfw.usage.circuit.tx"
          }
        }
      }
    }
  },
  "size": 0,
  "query": {
    "bool": {
      "filter": [
        {
          "range": {
            "@timestamp": {
              "format": "strict_date_optional_time",
              "gte": "now-24h",
              "lte": "now"
            }
          }
        }
      ]
    }
  }
}
'

Fetch Recent Alert Events​

Search the ziti.event* index for recent alerts

curl -k -X GET "{{ELASTICSEARCH_URL}}/zfw.events*/_search?pretty" \
     -u "yourusername:yourpassword" \
     -H 'Content-Type: application/json' -d''
{
  "query": {
    "bool": {
      "filter": [
        {
          "range": {
            "@timestamp": {
              "format": "strict_date_optional_time",
              "gte": "now-24h",
              "lte": "now"
            }
          }
        }
      ]
    }
  }
}
'

Notes & Best Practices​

  • Always include a time filter for large indices to improve performance.
  • Prefer keyword fields (e.g., field.keyword) for exact matches.
  • When using aggregations, set "size": 0 to avoid returning unnecessary document hits.
  • You can test queries interactively using Kibana Dev Tools.