Create custom behaviors

Create a custom behavior when the built-in catalogue does not describe a semantic pattern that matters to your product.

Enable Behaviors before creating a custom behavior. Changing this organization-level setting can require an organization admin.

Write a good definition

Describe one meaning that another person could label consistently. Define the boundary instead of listing keywords.

Definition	Example	Why
Specific	”The user changes the destination after an itinerary has been proposed.”	Gives `destination_changed` a clear boundary
Too broad	”Travel changes.”	Mixes destinations, dates, passengers, and other unrelated changes

Plan both matching and nearby non-matching examples before creating the behavior.

Create a draft

In Behaviors, select New custom behavior, then complete the draft:

Field	Guidance
Name	Use a unique lowercase `snake_case` name. It cannot reuse a built-in name and cannot be changed later.
Description	State what should match in one precise sentence.
Polarity	Choose positive, negative, or neutral. Custom behaviors default to neutral.

Polarity controls how the behavior is grouped in analytics; it does not change the classifier.

New custom behavior form with name, description, and polarity fields — A custom behavior starts with a stable name, a clear description, and a reporting polarity.

Add and review examples

Training requires:

4 to 200 examples
No more than 4,000 characters per example
At least one matching example and one non-matching example

Custom behavior draft showing zero of four examples, the matching and non-matching requirements, and the Start reviewing logs action — A new draft shows the example requirements and the action for starting a review session.

Choose a time range with representative traffic, then select Start reviewing logs. For each selected log:

Select Yes when the behavior applies.
Select No when it does not apply.
Select Skip when the example is ambiguous or not useful for training.

Use examples that express the same meaning in different words and tones. Include hard non-matches close to the boundary, not only obviously unrelated logs. Four examples satisfy the minimum but do not guarantee a reliable classifier.

Custom behavior review queue with a selected log and Skip, No, and Yes controls — Review real logs and label each one Yes, No, or Skip before training.

Train the behavior

Select Train behavior after the minimum example requirements are satisfied. Training is asynchronous and fits a lightweight classifier from your examples; it does not fine-tune a foundation model.

State	Meaning	Next action
Draft	The definition or examples are not trained	Add or review examples, then train
Training	A classifier is being prepared	Wait for the job to finish
Ready	The classifier can evaluate eligible spans	Investigate results or use it in the Logs filter
Failed	The asynchronous training job did not finish successfully	Retry; contact support if it fails repeatedly

If a retraining attempt fails, the previously ready classifier remains available. Retry the training job or contact support if failures continue.

Manage and improve the behavior

From the behavior’s actions menu, you can update its description or polarity, manage examples and tags, disable it without deleting it, or delete it when it is no longer needed. The name remains immutable.

Editing the examples returns a ready behavior to Draft and requires training again.
Editing only the description, polarity, or tags preserves its current training state.
Disabling a behavior stops new classification and hides it from behavior analytics and filters while retaining its configuration.

Correct an incorrect verdict

Feedback is available for custom behaviors. When a classified span has the wrong verdict:

Open the custom behavior result.
Flag the verdict as incorrect.
Wait while Respan applies the feedback asynchronously.

Feedback state	Meaning
Pending	The flag is queued and its corrective example has not been applied
Applied	The reversed-label example was added and a classifier refit was queued
Error	Respan could not recover the span text, so no corrective example was applied

Select Undo on a flagged result to remove its corrective example and queue another refit. This workflow does not change built-in behavior verdicts.

Troubleshoot

Problem	What to check
Training is unavailable	Add at least four examples, including both a Yes and a No
No result appears	Wait for classification, then verify that the span type and content are eligible
Training fails	Retry; if it fails repeatedly, contact support. A prior ready version remains available
An edit conflicts	Refresh the page and reapply the change
The behavior is missing from Logs	Finish training and wait for the behavior to reach Ready, then refresh the filter

Investigate behavior signals

Read behavior trends, inspect events, and filter the matching logs.