Express Production Logs: Query Shipment & Text Events
To query shipment and text events in Express Production logs, use the logs command with the --query flag, filtering by event type and date range. This guide explains the exact syntax, common filters, and how to interpret the results.
Background: What Are Express Production Logs?
Express Production (also known as Express Production Tracking) is a logistics platform used by shipping companies to manage parcels, freight, and delivery workflows. The system generates logs that record every action taken on a shipment—from label creation to final delivery—as well as text events, which are notifications sent to customers or internal staff via SMS or messaging services. These logs are stored in a structured format, typically JSON or CSV, and can be queried using the platform’s built-in command-line interface (CLI) or API.
The logs are essential for auditing, troubleshooting delivery issues, and ensuring compliance with service-level agreements. Without proper querying, finding a single event among millions can be like searching for a needle in a haystack.
How to Query Shipment Events
Shipment events are actions like “picked up,” “in transit,” “out for delivery,” and “delivered.” To query them, you use the logs command with a filter for the event type. Here’s the basic syntax:
express logs --type shipment --event delivered --from 2024-01-01 --to 2024-01-31This returns all delivery events within January 2024. You can also filter by shipment ID, tracking number, or carrier:
--shipment-id– Filter by a specific shipment’s unique identifier.--tracking-number– Filter by the customer-facing tracking number.--carrier– Filter by the carrier (e.g., UPS, FedEx, USPS).--status– Filter by the current status (e.g., pending, in_transit, delivered).
For a broader view, omit the --event flag to see all shipment events in a date range. The output includes timestamps, event codes, and any associated metadata like location or handler.
How to Query Text Events
Text events are notifications sent via SMS or other messaging channels. They are logged separately from shipment events but can be queried similarly. Use the --type text flag:
express logs --type text --from 2024-01-01 --to 2024-01-31You can narrow results by recipient phone number, template ID, or delivery status:
--recipient– Filter by the recipient’s phone number.--template– Filter by the message template used (e.g., “delivery_reminder”).--status– Filter by delivery status (e.g., sent, delivered, failed).
Text event logs typically include the message content, timestamp, and the carrier’s response (e.g., “delivered” or “undeliverable”). This is useful for debugging failed notifications.
Combining Filters for Complex Queries
You can combine multiple filters to answer specific questions. For example, to find all text notifications sent to a particular customer about a delayed shipment:
express logs --type text --recipient 555-1234 --template delay_notice --from 2024-01-15 --to 2024-01-20Similarly, to see the full lifecycle of a shipment, query both types and merge the results:
express logs --type shipment --tracking-number 1Z999AA10123456784Then run the same with --type text. The timestamps will show when each event occurred, giving you a complete timeline.
Common Problems and Misconceptions
One common mistake is confusing the --status flag with --event. The --status flag filters by the current state of the shipment, while --event filters by the specific action logged. For example, a shipment may have a status of “delivered” but contain multiple events (e.g., “out for delivery,” “delivered,” “signed”).
Another issue is timezone handling. Logs are stored in UTC by default. If you query without specifying a timezone, you might miss events that occurred late in the evening in your local time. Use the --timezone flag to set your local timezone, or convert your query times to UTC manually.
Some users expect text events to appear in the same log file as shipment events. In reality, they are separate streams. You must query them separately or use the API to join them. The CLI does not support cross-type queries in a single command.
How to Choose the Right Query Method
If you’re a developer or system administrator, the CLI is the fastest way to run ad-hoc queries. For recurring reports, consider using the REST API, which allows you to script queries and automate data extraction. The API supports the same filters but returns JSON, which is easier to parse programmatically.
For non-technical users, the web dashboard provides a visual query builder. You can select event types, date ranges, and filters from dropdown menus, then export the results as CSV. This is ideal for generating monthly reports without writing code.
Cost and Performance Considerations
Querying logs is free, but there are limits on how much data you can retrieve in one request. The CLI and API cap results at 10,000 records per query. If you exceed this, you’ll need to paginate using the --offset and --limit flags or use the API’s pagination tokens.
Performance-wise, queries on large date ranges (e.g., a full year) can be slow. To speed things up, narrow your date range as much as possible and use specific filters like shipment ID instead of scanning all events. Indexing is automatic, but the more selective your query, the faster it runs.
Alternatives to the Built-In Query Tools
If the built-in tools don’t meet your needs, you can export logs to a data warehouse like Amazon S3 or Google BigQuery and query them with SQL. This is useful for complex analytics, such as correlating shipment delays with text notification failures. The export feature is available in the dashboard under “Settings > Data Export.”
Alternatively, you can use third-party log management tools like Splunk or ELK stack by forwarding logs via webhook. This requires some setup but gives you powerful search and visualization capabilities.
Frequently Asked Questions
How do I query logs for a specific shipment ID?
Use the --shipment-id flag with the logs command. For example: express logs --type shipment --shipment-id SHIP12345. This returns all events for that shipment, sorted by timestamp.
Can I query text events by the message content?
No, the CLI does not support searching by message body. You can filter by template ID or recipient, but not by the actual text. To search content, you’d need to export logs and use a text editor or script.
What timezone are the log timestamps in?
By default, timestamps are in UTC. You can change this using the --timezone flag (e.g., --timezone America/New_York) to display times in your local timezone. The underlying data remains in UTC.
Why am I seeing duplicate events in my query results?
Duplicates can occur if the same event is logged multiple times due to retries or system errors. To avoid them, use the --distinct flag to deduplicate by event ID. If duplicates persist, check your filters—you might be overlapping date ranges.
How far back can I query logs?
Logs are retained for 13 months by default. After that, they are archived and no longer available via the CLI or API. For older data, you must have exported it before the retention period ended.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.