This guide introduces the detect_anomalies_online method for monitoring streaming time series data in real time. You’ll learn how to quickly get started with this method and explore its key differences from the historical anomaly detection endpoint.

​
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.

Univariate & Multivariate

Perform univariate and multivariate anomaly detection.

Stream Processing

Detect anomalies on stream data as it arrives.

​
Quick Start

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

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.

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.