Events API

Use this page to query event data from the zLAN indices in Elasticsearch, provided by the NetFoundry support stack. For more on the support stack, see the Self-Hosted documentation.

Elastic indices overview

Index Name	Description	Example Fields
zfw.events*	Ziti firewall usage broken down into granular dimensions such as firewall, 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.

warning

Substitute ELASTICSEARCH_URL with the local installation URL. The default access URL for the remote access user is https://elasticsearch.ziti. NetFoundry provides the URL, username, and password during Self-Hosted 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 and 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.