Skip to main content
Online anomaly detection helps you catch issues in real time—like spotting traffic spikes on a website. Using detect_anomalies_online, you can monitor the latest data with rolling forecasts. This guide shows you how to get started and how it differs from historical detection.

​
Overview

Online (real-time) anomaly detection helps you identify unusual behavior in time series data as soon as it appears. With TimeGPT, you can:

Flexible Control

More flexibility and control over the anomaly detection process.

Local & Global

Perform local and global anomaly detection.

Stream Processing

Detect anomalies on stream data as it arrives.

​
Quick Start

Open In Colab
1

1. Set up your environment

Initialize your Python environment by importing the required libraries:
Environment Setup
import pandas as pd
from nixtla import NixtlaClient
import matplotlib.pyplot as plt
2

2. Configure your NixtlaClient

Provide your API key (and optionally a custom base URL).
Nixtla Client Configuration
nixtla_client = NixtlaClient(
    # defaults to os.environ.get("NIXTLA_API_KEY")
    api_key='my_api_key_provided_by_nixtla'
)
Using an Azure AI endpoint
To use an Azure AI endpoint, set the base_url argument:
Azure AI Endpoint Setup
nixtla_client = NixtlaClient(
    base_url="your_azure_ai_endpoint",
    api_key="your_api_key"
)
3

3. Load your dataset

We use a minute-level time series dataset that monitors server usage. This dataset is ideal for showcasing streaming data scenarios, where the task is to detect server failures or downtime in real time.
Load Server Dataset
df = pd.read_csv(
    'https://datasets-nixtla.s3.us-east-1.amazonaws.com/machine-1-1.csv',
    parse_dates=['ts']
)
We observe that the time series remains stable during the initial period; however, a spike occurs in the last 20 steps, indicating anomalous behavior. Our goal is to capture this abnormal jump as soon as it appears.
Server Data with Spike Anomaly

Server Data with Spike Anomaly

4

4. Detect anomalies in real time

Use the detect_anomalies_online method to identify anomalies by leveraging TimeGPT’s forecasting capabilities.
Key Parameters
• df: A DataFrame containing your time series.
• time_col: Datestamp column.
• target_col: Variable to forecast.
• h: Forecast horizon (steps ahead).
• freq: Frequency (e.g., ‘min’).
• level: Confidence level (default 99%).
• detection_size: Number of recent steps to analyze for anomalies.
Run Online Anomaly Detection
anomaly_online = nixtla_client.detect_anomalies_online(
    df,
    time_col='ts',
    target_col='y',
    freq='min',                # Specify the frequency of the data
    h=10,                      # Specify the forecast horizon
    level=99,                  # Set the confidence level for anomaly detection
    detection_size=100         # Number of steps to analyze for anomalies
)

anomaly_online.tail()
Here we use a detection size of 100 to illustrate the anomaly detection process. In production, running detections more frequently with smaller detection sizes can help identify anomalies as soon as they occur.
Log Output
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Calling Online Anomaly Detector Endpoint...
unique_idtsyTimeGPTanomalyanomaly_scoreTimeGPT-hi-99TimeGPT-lo-99
machine-1-1_y_292020-02-01 22:11:000.6060170.544625True18.4632660.5531610.536090
machine-1-1_y_292020-02-01 22:12:000.0444130.570869True-158.9338500.5794040.562333
machine-1-1_y_292020-02-01 22:13:000.0386820.560303True-157.4748800.5688390.551767
machine-1-1_y_292020-02-01 22:14:000.0243550.521797True-150.1782400.5303330.513261
machine-1-1_y_292020-02-01 22:15:000.0444130.467860True-127.8485600.4763960.459325
Identified Anomalies

Identified Anomalies

5

5. Next steps

From the plot, we observe that the anomalous period is promptly detected. For a deeper dive into detect_anomalies_online—including parameter tuning and strategies for fine-tuning anomaly detection—stay tuned for our upcoming tutorial.
⌘I