Learning Coverage has not increased for a long time; why?

Short answer

Learning Coverage shows what percentage of the requests that fell within the learning scope in the last 24 hours, contain no attack and received a response below 400 consist of previously seen request shapes. Only the requests that come to host groups in Learning Mode and the requests that come with a Conditional Learning identity enter the learning scope. There are three reasons why the value does not increase: the site constantly produces new shapes (a shape consists of the method, host, path, parameter names and value length ranges, body field names, header names, triggered signatures and the response code; paths that carry an ID or a date count as a new shape on every request), the value is not calculated and the indicator stays empty because the number of requests that meet these conditions in the last 24 hours stayed below 100, or most of the traffic does not enter the calculation because it received a 4xx/5xx response or contained an attack. Which one is happening is shown by the New shapes (accepted) line in the Learning Discovery Rate panel and by the Learning Log Sampling panel. If the Learning tab is not visible at all, Smart Sampling (learning log) is off, or there is no host group in Learning mode and Conditional learning is off. Whether the learning is finished is not decided by this metric alone: How long does learning take; how do I know it is finished?

Problem: Learning Coverage Stays Flat

On the Learning tab of the vService's Dashboard, Learning Coverage has stayed at the same level for days or appears empty; it cannot be understood whether the learning is progressing and whether it is sufficient to move to Monitor mode. Without knowing what the metric counts and what it does not count, a flat line is misinterpreted: the value measures not the quality of the rule set, but how much of the incoming traffic consists of familiar shapes (What do Learning Coverage and Learning Discovery Rate mean?).

How Is Learning Coverage Calculated?

1. A request enters the learning scope when it falls into a host group in Learning Mode or when it carries a Conditional Learning identity. Requests that come to host groups in Blocking Mode and Monitor Mode do not enter this scope; nor does being recognized by Teacher by itself bring a request into the learning scope.
2. The shape of the request is extracted: the method, host, path, query parameter names and value length ranges, the body type and the top-level field names of the body, header names, triggered signatures and the response status code. The values themselves do not enter the shape (Smart Sampling (learning log)).
3. The request is placed in one of three classes: containing an attack; containing no attack and receiving a response of 400 or above; containing no attack and receiving a response below 400. Learning Coverage counts only the third class.
4. The value is calculated by subtracting the share of the requests whose shape is seen for the first time, among the requests seen in this class in the last 24 hours: 100 × (1 − new-shape requests / total requests). If the total in the last 24 hours is below 100, no value is produced and that interval appears empty.
5. If a shape is not seen at all for about three weeks, it is forgotten; when the upper limit of the shape memory is reached, the oldest shapes can also drop out before this period. A forgotten shape counts as new when it comes again.

Possible Causes

Symptom	Cause	How to tell it apart
There is no Learning tab at all	Smart Sampling (learning log) is off, or there is no host group in Learning mode and Conditional Learning is off	The "Sampling is off — every request is written in full (only advisable on low traffic)" sentence on the Log Settings card; no Learning mode on the mode cards
The indicator is empty, the line is intermittent	In the last 24 hours, the number of requests in the learning scope that contain no attack and received a response below 400 is below 100	In the Learning Log Sampling panel, the Written and Skipped slices are very small or zero
The indicator is empty; Conditional learning is on but no host group is in Learning mode	The Conditional learning switch is on, but the identity is not defined or there is no traffic that carries the identity	The "Conditional learning is on but no identity is set" warning on the Learning Methods card
The value stays at a certain level, New Shapes (accepted) does not drop to zero	The site constantly produces new shapes: paths that carry an ID, a date or an order number, randomly generated parameter or JSON field names, parameters whose value length constantly changes	In the Learning Discovery Rate panel, the New shapes (accepted) line does not flatten
The value stays low or fluctuates; the traffic is heavy	Most of the traffic receives a 4xx/5xx response or contains an attack; these requests do not enter the calculation, and the small portion that does enter the calculation also consists of new shapes	New Shapes (attack) is dominant in Learning Discovery Rate; the 4xx/5xx rate is high in HTTP Logs
The value rises for a while and then drops	A new domain name was added to the host group in Learning mode or a new section of the site was put live; since the host and the path are part of the shape, all of its requests count as new	The moment the value drops coincides with a release or a DNS change
Rarely opened pages constantly appear new	Shapes that come about once every three weeks or more rarely are forgotten, so they count as new again	The drops coincide with specific reporting or campaign days

Definitive rules:

• The Learning tab is visible only on an HTTP vService, while Smart Sampling (learning log) has not been turned off and while at least one host group is in Learning mode or the Conditional learning switch is on. When all host groups are moved to Monitor mode or Blocking mode and Conditional learning is off, the tab disappears.
• The metric is a single value for the whole vService; it is not split per host group. The new shapes of one host group in Learning mode pull the whole value down.
• The Sampling: Full Copies per Shape value does not change Learning Coverage: the written (Written) and skipped (Skipped) requests are counted in the same total.
• Collecting paths into a single page type with Dynamic Paths in Analysis & Learning does not change the metric; the shape is formed with the raw path of the request.
• In a cluster setup, which device's data is shown is selected with the Source field in the Dashboard settings (default Both Devices).

Where Is It Monitored?

Screen	Path	What it shows
Learning Coverage	WAF-Protected vServices → vService → Dashboard → Learning	The percentage for the last 24 hours; indicator and line chart
Learning Discovery Rate	Same tab	The number of new shapes per second: New shapes (accepted) and New shapes (attack)
Learning Log Sampling	Same tab	The share of the requests entering the learning scope that is written (Written) and skipped (Skipped)
WAF Inspection Distribution	Dashboard → Summary	The Learning series shows the volume of requests in the learning scope
The mode cards and the Learning Methods card	WAF-Protected vServices → vService → WAF Management	The mode of the host groups and the status of Conditional learning

How to Diagnose?

1. Left Monitor Panel → WAF-Protected vServices → vService is opened; the screen opens with the Dashboard tab. If there is no Learning tab, the diagnosis continues with step 6.
2. The Learning Log Sampling panel is examined. If the total of Written and Skipped is very small, not enough traffic is entering the learning scope; if the indicator is empty or intermittent, the requests entering the calculation in the last 24 hours are below 100.
3. In the Learning Discovery Rate panel, the trend of the New Shapes (accepted) line is examined. If the line decreases over time, the learning is progressing and Learning Coverage rises with a delay; if the line stays at the same level, the site is constantly producing new shapes.
4. If the New Shapes (attack) line is clearly higher than the accepted line, a significant part of the traffic contains attacks; these requests do not enter the Learning Coverage calculation.
5. Left Monitor Panel → Load Balancer vServices → vService → Logs & Tracking → HTTP Logs is opened; the response codes are examined. If the 4xx/5xx rate is high, these requests also stay out of the calculation (HTTP Logs). The screen requires monitoring permission in the Load Balancer area.
6. Left Monitor Panel → WAF-Protected vServices → vService → WAF Management is opened. Whether there is Learning mode on the mode cards, the Conditional learning sentence on the Learning Methods card in the Learning & Reporting section and the sampling sentence on the Log Settings card are examined.

Solution

In most cases, the value staying flat is not a configuration error: as the site produces new shapes, Learning Coverage shows this correctly, and dynamic paths are collected separately in the rule set (What are Dynamic Paths, Excluded Paths and Dynamic Path Exclusions for?). For the two situations caused by the configuration, the methods below are used.

Your situation	Suitable method
The host groups are in Monitor mode or Blocking mode; I want to continue learning with the traffic of specific users	Method 1: Defining a Conditional learning identity
The Learning tab is not visible; the Log settings card says that sampling is off	Method 2: Turning on Smart Sampling (learning log)
The site constantly produces new shapes	No method is needed; whether the learning is finished is decided with other indicators: How long does learning take; how do I know it is finished?

Method 1: Defining a Conditional Learning Identity Recommended

• How it works The requests whose identity matches enter the learning scope regardless of the mode of the host group: they are not scored, not blocked and are written to the learning log; signature scanning continues for the learning, and structural rules are not applied (Conditional Learning). These requests feed Learning Coverage.
• Where it is opened WAF-Protected vServices → vService → WAF Management → Learning & Reporting → Learning Methods card
• Requirement Modify permission in the WAF area; the IPv4 addresses of the users who will carry the identity, or the TR7-ANALYZE cookie or header value they will send
• Scope The whole vService; all host groups

Step-by-Step Configuration

1

Adım 1 Open the WAF Management tab

Left Monitor Panel → WAF-Protected vServices → vService → WAF Management is opened.

2

Adım 2 Open the Learning Methods window

The pencil icon of the Learning Methods card in the Learning & Reporting section is clicked; the Learning Methods window opens.

3

Adım 3 Turn on Conditional Learning

The Conditional Learning switch is turned on (it is off by default); the Conditional Learning IP, Conditional Learning Cookie and Conditional Learning Header fields appear below it.

4

Adım 4 Enter the identity

In the IP field, IPv4 addresses and IPv4 blocks are written separated by a space (e.g. 203.0.113.0/24); IPv6 addresses and comma-separated entries are ignored at run time. In the cookie or header field, the value of the cookie or header named TR7-ANALYZE is written; the value is compared exactly. The form does not validate the format of these fields. If TR7 is behind a CDN or proxy, for the IP identity, the Trusted Proxy configuration on the The logs show the proxy / CDN IP instead of the client IP; what should I do? page is done first.

5

Adım 5 Save

Edit is clicked; the setting is applied without a separate deployment step. In a cluster setup, the change is also sent to the peer device with the default auto-sync; if Manual Sync Mode is on, it is sent with Synchronize.

Requests that carry the identity are not blocked

The requests whose identity matches pass without being blocked even in a host group in Blocking mode. The identity is kept narrow, and when the work is finished, the identity fields are emptied and saved while the switch is on: when the switch is turned off, the saved identities are not deleted and continue to match; also, while the switch is off, a change in the fields is not saved (Can I still keep learning certain traffic while in Blocking mode (Conditional Learning)?).

Verification

1Learning Methods cardTR7 side

The Learning methods card in WAF Management is examined.

ExpectedConditional learning is on — the analyst is recognised by IP

In the sentence, the filled identity fields (IP, cookie, header) are written joined with "+".

2Learning tabTR7 side

After the users who carry the identity browse the site, the Learning Log Sampling panel on the Dashboard → Learning tab is examined.

ExpectedThe Written slice increases

Method 2: Turning On Smart Sampling (Learning Log)

• How it works The Learning tab and the Learning Coverage, Learning Discovery Rate and Learning Log Sampling panels in it are visible only while sampling is on (What is Smart Sampling; how does it affect the learning log?).
• Where it is opened WAF-Protected vServices → vService → WAF Management → Learning & Reporting → Log Settings card
• Requirement Modify permission in the WAF area
• Scope The whole vService; HTTP vService only

Step-by-Step Configuration

1

Adım 1 Open the WAF Management tab

Left Monitor Panel → WAF-Protected vServices → vService → WAF Management is opened.

2

Adım 2 Open the Log Settings window

The pencil icon of the Log Settings card in the Learning & Reporting section is clicked; the Log Settings window opens.

3

Adım 3 Turn on sampling

The Smart Sampling (learning log) box is checked (it is checked by default). The Sampling: Full Copies per Shape field that appears below it can be left at its default value of 50; this value does not change Learning Coverage.

4

Adım 4 Save

Edit is clicked; the setting is applied without a separate deployment step. In a cluster setup, the change is also sent to the peer device with the default auto-sync; if Manual Sync Mode is on, it is sent with Synchronize.

Verification

1Log Settings cardTR7 side

The Log settings card in WAF Management is examined.

ExpectedThe learning log is smart-sampled — the first 50 of each request shape are written in full

The Learning tab appears on the Dashboard while at least one host group is in Learning mode or Conditional learning is on; the value is calculated after at least 100 requests have accumulated in the last 24 hours.

Common Mistakes

• Taking the empty indicator for zero. If the requests entering the calculation in the last 24 hours are below 100, the value is not calculated; the gap means "insufficient data".
• Expecting the metric to increase after moving to Monitor mode. The traffic of host groups in Monitor mode and Blocking mode does not enter the learning scope; only Learning mode and the Conditional learning identity feed the metric.
• Thinking that Teacher will feed the metric. In a host group in Monitor mode or Blocking mode, the requests recognized by Teacher do not enter the learning scope; Teacher clears false positives from the rules, it does not count shapes.
• Taking the New shapes (attack) line for learning progress. Requests that contain an attack do not enter the Learning Coverage calculation; clients that perform scans keep raising this line.
• Thinking that Dynamic paths will raise the metric. Path collection in Analysis & Learning changes the rule set; since the shape is formed with the raw path, the metric does not change.
• Not moving to Monitor mode until Learning Coverage is 100%. On sites with paths that carry an ID, the value does not reach 100%; the decision to switch is made by verifying that no false positives are produced in Monitor mode (When should I move from Learning to Monitor and from Monitor to Blocking?).

How it is done in the documentation

• Dashboard · Learning Coverage
• Dashboard · Learning Discovery Rate
• Dashboard · Learning Tab
• Log Settings · Smart Sampling (Learning Log)
• Learning Methods · Conditional Learning

Related questions

• What do Learning Coverage and Learning Discovery Rate mean?
• How long does learning take; how do I know it is finished?
• What is Smart Sampling; how does it affect the learning log?
• Which tabs does the WAF Dashboard have (Summary, Attack Analysis, Learning); why is the Learning tab not always visible?