Signals
Signals are labels that Steel adds to a session after the session ends. They mark events from the run, such as a CAPTCHA, a bot block or a proxy failure. Use them to find the sessions to check, without opening each recording. You do not set signals. To add your own labels, use metadata.
Before you begin
Put your Steel API key in the STEEL_API_KEY environment variable, and install the Steel SDK for your language: TypeScript, Python, Go or Rust.
Read a session's signals
A session's signals field is an array of signal names. It stays empty while the session runs, and Steel fills it in after the session ends.
This program creates a session with an inactivityTimeout of 5 seconds, so Steel releases it after 5 seconds without activity. The program does nothing in the session. It waits 20 seconds, then prints the session's signals as JSON.
import Steel from "steel-sdk";
const client = new Steel();
const session = await client.sessions.create({ inactivityTimeout: 5000 });
try {
console.log(`Created session ${session.id}`);
await new Promise((resolve) => setTimeout(resolve, 20_000));
const { signals } = await client.sessions.retrieve(session.id);
console.log(JSON.stringify(signals));
} finally {
await client.sessions.release(session.id);
}import json
import time
from steel import Steel
client = Steel()
session = client.sessions.create(inactivity_timeout=5000)
try:
print(f"Created session {session.id}")
time.sleep(20)
signals = client.sessions.retrieve(session.id).signals
print(json.dumps(signals))
finally:
client.sessions.release(session.id)package main
import (
"context"
"encoding/json"
"fmt"
"log"
"time"
"github.com/steel-dev/sdk/go"
)
func main() {
if err := run(context.Background()); err != nil {
log.Fatal(err)
}
}
func run(ctx context.Context) error {
client := steel.NewClient()
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
InactivityTimeout: steel.F(int64(5000)),
})
if err != nil {
return err
}
defer func() {
if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
log.Print(err)
}
}()
fmt.Printf("Created session %s\n", session.ID)
time.Sleep(20 * time.Second)
current, err := client.Sessions.Get(ctx, session.ID)
if err != nil {
return err
}
signals, err := json.Marshal(current.Signals)
if err != nil {
return err
}
fmt.Println(string(signals))
return nil
}#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = steel_rs::Client::new();
let session = client
.sessions()
.create(steel_rs::SessionCreateParams {
inactivity_timeout: Some(5000),
..Default::default()
})
.await?;
let result: Result<(), Box<dyn std::error::Error>> = async {
println!("Created session {}", session.id);
tokio::time::sleep(std::time::Duration::from_secs(20)).await;
let current = client.sessions().retrieve(&session.id).await?;
println!("{}", serde_json::to_string(¤t.signals)?);
Ok(())
}
.await;
client.sessions().release(&session.id).await?;
result
}In Rust, the program also needs cargo add serde_json. Run the program:
npx tsx signals.mtspython signals.pygo run .cargo runThe session ended on its inactivityTimeout, so it has the signal session_timeout_exceeded:
Created session d14e97be-2e61-4f5f-880e-189558bd4bc3
["session_timeout_exceeded"]A session that hit a CAPTCHA and a bot block has this list:
["captcha_encountered", "bot_detection_triggered"]Signals reference lists every signal and what it means. It also explains why an empty list does not prove that nothing happened. To learn why a session ended, read its releaseReason. See Session lifecycle.
The sessions that sessions.list returns carry the same field. The dashboard shows signals in the session list and in the session viewer.
Show signals in your app
Steel can add new signal names over time, so handle names that you do not know. To show signals in your own app without a fixed list, call sessions.signalCatalog (sessions.signal_catalog in Python, Sessions.SignalCatalog in Go and sessions().signal_catalog in Rust). It returns each current signal with a label, a description and a severity of info, warning, danger or success.
const catalog = await client.sessions.signalCatalog();
for (const signal of catalog.signals) {
console.log(signal.value, signal.label, signal.severity);
}catalog = client.sessions.signal_catalog()
for signal in catalog.signals:
print(signal.value, signal.label, signal.severity)catalog, err := client.Sessions.SignalCatalog(ctx)
if err != nil {
return err
}
for _, signal := range catalog.Signals {
fmt.Println(signal.Value, signal.Label, signal.Severity)
}let catalog = client.sessions().signal_catalog().await?;
for signal in catalog.signals {
println!("{:?} {} {:?}", signal.value, signal.label, signal.severity);
}Find sessions by signal
Pass signal to sessions.list to find the sessions that carry a signal. If you pass several signals, a session must carry all of them. Add metadata to narrow the search to one job or one customer.
for await (const session of client.sessions.list({
metadata: { job_id: "job-1042" },
signal: ["bot_detection_triggered"],
})) {
console.log(session.id, session.signals);
}for session in client.sessions.list(
metadata={"job_id": "job-1042"},
signal=["bot_detection_triggered"],
):
print(session.id, session.signals)iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
Metadata: steel.F(map[string]string{"job_id": "job-1042"}),
Signal: steel.F([]steel.SessionListParamsSignal{steel.SessionListParamsSignalBotDetectionTriggered}),
})
for iter.Next() {
session := iter.Current()
fmt.Println(session.ID, session.Signals)
}
if err := iter.Err(); err != nil {
return err
}let sessions = client
.sessions()
.list_auto_paging(steel_rs::SessionListParams {
metadata: Some(std::collections::HashMap::from([(
"job_id".to_owned(),
"job-1042".to_owned(),
)])),
signal: Some(vec![
steel_rs::SessionListParamsSignal::BotDetectionTriggered,
]),
..Default::default()
});
let mut sessions = std::pin::pin!(sessions);
while let Some(session) = futures_util::StreamExt::next(&mut sessions).await {
let session = session?;
println!("{} {:?}", session.id, session.signals);
}In Rust, this code needs cargo add futures-util.
Over HTTP, repeat the signal parameter for each signal:
curl -G https://api.steel.dev/v1/sessions \
-H "steel-api-key: $STEEL_API_KEY" \
--data-urlencode "signal=captcha_encountered" \
--data-urlencode "signal=bot_detection_triggered"The list leaves out failed sessions unless you pass status or releaseReason.
Check that it worked
List the sessions that carry session_timeout_exceeded, as Find sessions by signal shows. The session that the program in Read a session's signals created is in the list, with the signal that the program printed. The dashboard's session list shows the same signal for it.