Logs Module
The Logs module (oloClient.logs / client.logs) provides access to script execution logs stored on the appliance. This enables reading, querying, and searching log output from previous script executions with fine-grained filtering options.
Key Features
- Read logs from appliance file storage via WebSocket for lowest latency
- Filter by date/time range, script name, content search
- Quick helpers for tail (last N lines) and error-only filtering
- Search across multiple executions
- Pagination for large log files
Quick Start
Get last 50 lines of a recent execution:
// List recent executions
const result = await oloClient.logs.listExecutions({ limit: 5 });
console.log('Recent executions:', result.executions.map(e => e.scriptName));
// Get last 50 lines from the most recent execution
const executionId = result.executions[0].executionId;
const logs = await oloClient.logs.tail(executionId, 50);
logs.logs.forEach(log => {
console.log(`[${log.timestamp}] [${log.type}] ${log.message}`);
});Listing Executions
listExecutions(options) / list_executions(**options)
List execution logs with optional filtering.
| Parameter | Type | Description |
|---|---|---|
scriptName | string | Filter by script name (partial match) |
scriptId | string | Filter by script ID (exact match) |
startDate | string | Filter executions after this date (ISO string) |
endDate | string | Filter executions before this date (ISO string) |
limit | number | Maximum results (default: 50) |
offset | number | Pagination offset (default: 0) |
Returns: Object with executions array, total count, and pagination info.
// List all executions for a specific script
const result = await oloClient.logs.listExecutions({
scriptName: 'patrol',
startDate: '2025-01-01T00:00:00Z',
limit: 20
});
console.log(`Found ${result.total} executions, showing ${result.executions.length}`);
result.executions.forEach(exec => {
console.log(`${exec.scriptName} - ${exec.startedAt} (${exec.sizeFormatted})`);
});Getting Logs
getLogs(options) / get_logs(**options)
Get log entries with filtering options.
| Parameter | Type | Description |
|---|---|---|
executionId | string | Execution ID (required) |
lines | number | Return last N lines (tail mode) |
startDate | string | Filter entries after this timestamp |
endDate | string | Filter entries before this timestamp |
search | string | Filter entries containing this text |
type | string | Filter by type: 'stdout' or 'stderr' |
offset | number | Pagination offset (default: 0) |
limit | number | Maximum entries (default: 1000) |
Returns: Object with logs array, metadata, and pagination info.
// Get logs with content filtering
const result = await oloClient.logs.getLogs({
executionId: 'abc-123-def',
search: 'error',
type: 'stderr',
limit: 100
});
console.log(`Found ${result.total} matching entries`);
result.logs.forEach(log => {
console.log(`[${log.timestamp}] ${log.message}`);
});Quick Helpers
tail(executionId, lines) / tail(execution_id, lines)
Get last N lines of a log.
const result = await oloClient.logs.tail('abc-123', 100);
console.log(`Last ${result.logs.length} entries:`);
result.logs.forEach(log => console.log(log.message));search(query, options) / search(query, **options)
Search across multiple execution logs.
| Parameter | Type | Description |
|---|---|---|
query | string | Search text (required) |
scriptName | string | Filter by script name |
startDate | string | Filter by date range start |
endDate | string | Filter by date range end |
limit | number | Max results per execution (default: 10) |
maxExecutions | number | Max executions to search (default: 20) |
const result = await oloClient.logs.search('connection failed', {
scriptName: 'robot_control',
startDate: '2025-01-01T00:00:00Z'
});
console.log(`Found matches in ${result.executionsWithMatches} executions`);
result.results.forEach(r => {
console.log(`${r.scriptName}: ${r.matchCount} matches`);
r.matches.forEach(m => console.log(` - ${m.message}`));
});getErrors(executionId, options) / get_errors(execution_id, **options)
Get only stderr (error) logs from an execution.
const errors = await oloClient.logs.getErrors('abc-123');
if (errors.logs.length > 0) {
console.log('Errors found:', errors.logs.length);
errors.logs.forEach(e => console.error(e.message));
}getByDateRange(executionId, startDate, endDate, options)
Get logs within a specific time window.
const result = await oloClient.logs.getByDateRange(
'abc-123',
'2025-01-15T10:00:00Z',
'2025-01-15T11:00:00Z'
);
console.log(`Logs from 10:00-11:00: ${result.logs.length}`);Metadata and Management
getMetadata(executionId) / get_metadata(execution_id)
Get detailed metadata about an execution log.
const meta = await oloClient.logs.getMetadata('abc-123');
console.log(`Script: ${meta.scriptName}`);
console.log(`Language: ${meta.language}`);
console.log(`Started: ${meta.startedAt}`);
console.log(`Entries: ${meta.entryCount}`);
console.log(`Size: ${meta.sizeFormatted}`);deleteLog(executionId) / delete_log(execution_id)
Delete an execution log from the appliance.
await oloClient.logs.deleteLog('abc-123');
console.log('Log deleted');Log Entry Structure
Each log entry contains:
| Field | Type | Description |
|---|---|---|
timestamp | string | ISO timestamp when the entry was logged |
type | string | 'stdout' for normal output, 'stderr' for errors |
message | string | The log message content |
Execution Metadata Structure
| Field | Type | Description |
|---|---|---|
executionId | string | Unique execution identifier |
scriptName | string | Name of the script |
scriptId | string | Script ID (if saved script) |
language | string | Programming language ('javascript' or 'python') |
startedAt | string | ISO timestamp when execution started |
size | number | Log file size in bytes |
sizeFormatted | string | Human-readable size (e.g., "2.5 KB") |
entryCount | number | Number of log entries |
firstEntry | string | Timestamp of first log entry |
lastEntry | string | Timestamp of last log entry |
Cloud Synced Logs
In addition to appliance logs (accessed via oloClient.logs), script execution logs are automatically synced to the cloud after each execution. Cloud logs provide:
- Persistence - Logs remain available even if the appliance is offline or restarted
- Cross-device access - View logs from any device via REST API
- Historical archive - Long-term storage beyond appliance capacity
Cloud logs are accessed via REST API endpoints, not through the OLO SDK. You need an authentication token to access them.
List Log Batches
GET /output/batches?limit=10&offset=0&scriptId=optional
Authorization: Bearer <token>Returns batches (grouped by execution), each containing:
| Field | Type | Description |
|---|---|---|
batch_id | string | Unique batch identifier |
script | object | Script info (id, name) |
log_count | number | Number of log entries |
first_log_time | string | Timestamp of first log |
last_log_time | string | Timestamp of last log |
// Example: Fetch recent log batches
const response = await fetch('https://app.olo-robotics.com/output/batches?limit=5', {
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
data.batches.forEach(batch => {
console.log(`${batch.script?.name}: ${batch.log_count} logs`);
});Get Logs for a Batch
GET /output/logs?batchId=<id>&limit=100&offset=0
Authorization: Bearer <token>Query parameters:
| Parameter | Type | Description |
|---|---|---|
batchId | string | Batch ID (required) |
scriptId | string | Filter by script ID |
search | string | Filter logs containing text |
startDate | string | Filter by date range start |
endDate | string | Filter by date range end |
limit | number | Max results (default: 1000) |
offset | number | Pagination offset |
// Example: Fetch logs for a specific batch
const response = await fetch(`https://app.olo-robotics.com/output/logs?batchId=${batchId}&limit=50`, {
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
data.logs.forEach(log => {
console.log(`[${log.timestamp}] ${log.message}`);
});Search Across Batches
GET /output/batches/search?search=<query>&scriptId=optional
Authorization: Bearer <token>Search for batches containing specific text in their logs.
Delete a Batch
DELETE /output/batch/<batchId>
Authorization: Bearer <token>Appliance vs Cloud Logs
| Feature | Appliance Logs (oloClient.logs) | Cloud Logs (REST API) |
|---|---|---|
| Access method | WebSocket via SDK | REST API with auth token |
| Availability | Requires appliance connection | Available anytime |
| Latency | Lowest (direct connection) | Higher (cloud round-trip) |
| Storage | Limited by appliance disk | Cloud storage limits |
| Real-time | Yes | Synced after execution |
For real-time log access during script development, use appliance logs. For historical analysis, dashboards, or when the appliance is unavailable, use cloud logs.