THIS REPOSITORY HAS BEEN MOVED TO https://github.com/F5Networks/SecondSight This copy is archived here for archival purposes.

This tool helps tracking NGINX OSS and NGINX Plus instances managed by NGINX Instance Manager/NGINX Management Suite, and TMOS (BIG-IP, VIPRION, BIG-IP Virtual Edition) instances managed by BIG-IQ

It has been tested against:

• NGINX Instance Manager/NGINX Management Suite 2.1.0, 2.2.0, 2.3.0
• BIG-IQ 8.1.0, 8.1.0.2, 8.2.0

Communication to NGINX Instance Manager / BIG-IQ is based on REST API, current features are:

• REST API and high level reporting - see usage page
• JSON Telemetry mode
  • POSTs instance statistics to a user-defined HTTP(S) URL (STATS_PUSH_MODE: CUSTOM)
  • Basic authentication support
  • Configurable push interval (in seconds)
• Grafana visualization mode
  • Pushes instance statistics to pushgateway (STATS_PUSH_MODE: PUSHGATEWAY)
• Automated e-mail reporting
  • Sends an email containing the report JSON file as an attachment named nginx_report.json for NGINX Instance Manager, and bigip_report.json for BIG-IQ
  • Support for plaintext SMTP, STARTTLS, SMTP over TLS, SMTP authentication, custom SMTP port
  • Configurable push interval (in days)
• HTTP(S) proxy support
• Realtime CVE tracking
• Resource and applications telemetry (currently supported for BIG-IQ)

For additional dashboards see the grafana page

BIG-IQ analytics

NGINX Instance Manager analytics

High level

graph TD
BIGIQ([BIG-IQ CM])
NIM([NGINX Instance Manager])

User([User / external app])
P2S[[F5 Telemetry Tracker]]
EMAIL[[e-mail server]]
BROWSER([Browser])
MYF5([External REST endpoint])

TMOSVE([TMOS VE])
BIGIP([BIG-IP])
VIPRION([VIPRION])
NGINXOSS([NGINX OSS])
NGINXPLUS([NGINX Plus])

P2S -- REST API --> BIGIQ 
P2S -- REST API --> NIM

BIGIQ --> TMOSVE
BIGIQ --> BIGIP
BIGIQ --> VIPRION

NIM --> NGINXOSS
NIM --> NGINXPLUS

User -- REST API --> P2S
P2S -- Usage JSON --> User

P2S -- e-mail w/JSON attachment --> EMAIL

BROWSER -- HTTP --> P2S
P2S -- Grafana Dashboard --> BROWSER
P2S -- Telemetry Call Home --> MYF5

JSON telemetry mode

sequenceDiagram
    participant Control Plane
    participant F5 Telemetry Tracker
    participant Third party collector
    participant REST API client
    participant Email server

    loop Telemetry aggregation
      F5 Telemetry Tracker->>Control Plane: REST API polling
      F5 Telemetry Tracker->>F5 Telemetry Tracker: Raw data aggregation
    end
    F5 Telemetry Tracker->>Third party collector: Push JSON reporting data
    REST API client->>F5 Telemetry Tracker: Fetch JSON reporting data
    F5 Telemetry Tracker->>Email server: Email with attached JSON reporting data

Grafana visualization mode

sequenceDiagram
    participant Control Plane
    participant F5 Telemetry Tracker
    participant Pushgateway
    participant Prometheus
    participant Grafana

    loop Telemetry aggregation
      F5 Telemetry Tracker->>Control Plane: REST API polling
      F5 Telemetry Tracker->>F5 Telemetry Tracker: Raw data aggregation
    end
    F5 Telemetry Tracker->>Pushgateway: Push telemetry
    Prometheus->>Pushgateway: Scrape telemetry
    Grafana->>Prometheus: Visualization

• Kubernetes/Openshift cluster or Linux host with Docker support
• Private registry to push the F5 Telemetry Tracker image
• One of:
  • NGINX Instance Manager 2.1.0, 2.2.0, 2.3.0
  • BIG-IQ 8.1.0, 8.1.0.2, 8.2.0
• SMTP server if automated email reporting is used
• NIST NVD REST API Key for full CVE tracking (https://nvd.nist.gov/developers/request-an-api-key)

This is the recommended method to run F5 Telemetry Tracker on a Linux virtual machine. Refer to installation instructions

F5 Telemetry Tracker requires:

• Any Linux distribution
• Python 3 (tested on 3.9+)
• FastAPI
• Uvicorn
• Requests
• XLSX Writer
• Pandas
• json2html
• clickhouse-driver

Dependencies can be installed using:

$ cd f5tt
$ pip install -r requirements.txt

f5tt/f5tt.sh is a sample script to run F5 Telemetry Tracker from bash

F5 Telemetry Tracker image is available on Docker Hub as:

fiorucci/f5-telemetry-tracker:latest

File 1.f5tt.yaml references such image by default.

If you need to build and push the docker image to a private registry:

git clone fabriziofiorucci/F5-Telemetry-Tracker
cd F5-Telemetry-Tracker/f5tt

docker build --no-cache -t PRIVATE_REGISTRY:PORT/f5-telemetry-tracker:latest .
docker push PRIVATE_REGISTRY:PORT/f5-telemetry-tracker:latest

Deploy on Kubernetes/Openshift:

cd F5-Telemetry-Tracker/manifests

Edit 1.f5tt.yaml to customize:

• image name:
  • To be set to your private registry image (only if not using the image available on Docker Hub)
• environment variables:

• Ingress host:
  • By default it is set to f5tt.ff.lan

For standalone operations (ie. REST API + optional push to custom URL):

kubectl apply -f 0.ns.yaml
kubectl apply -f 1.f5tt.yaml

To push statistics to pushgateway also apply:

kubectl apply -f 2.prometheus.yaml
kubectl apply -f 3.grafana.yaml
kubectl apply -f 4.pushgateway.yaml

By default 2.prometheus.yaml is configured for push mode, it must be edited decommenting the relevant section for pull mode

To setup visualization:

• Grafana shall be configured with a Prometheus datasource using by default http://prometheus.f5tt.ff.lan
• Import the contrib/grafana/F5-Telemetry-Tracker.json sample dashboard in Grafana

Service names created by default as Ingress resources are:

• f5tt.ff.lan - REST API and Prometheus scraping endpoint
• pushgateway.f5tt.ff.lan - Pushgateway web GUI
• prometheus.f5tt.ff.lan - Prometheus web GUI
• grafana.f5tt.ff.lan - Grafana visualization web GUI

Additional tools can be found here

• BIG-IQ Collector - Offline BIG-IQ inventory processing
• F5TT on BIG-IQ Docker - Run F5TT onboard BIG-IQ CM virtual machine
• Report Generator - Offline report generator
• Grafana - Sample Grafana dashboards
• FastAPI - FastAPI backend with integrated agent
• Postman - Sample Postman collection to test and run F5TT
• Docker compose - Run F5TT on docker-compose
• Kubernetes - Run F5TT on kubernetes to track NGINX usage based on NGINX Instance Manager

See F5 Support solutions:

• K83394355: How to count the number of NGINX instances with F5 Telemetry Tracker on NGINX Instance Manager - https://support.f5.com/csp/article/K83394355
• K29144504: How to install and use (Offline) F5 Telemetry collection Script on BIG-IQ - https://support.f5.com/csp/article/K29144504
• K94129313: How to install and use Docker F5 Telemetry collection script - https://support.f5.com/csp/article/K94129313

See the usage page