Docs

Torch Log Service

CLI reference

TLS CLI overview

This section introduces the CLI tools provided by Volcengine TLS.

How it works

Volcengine TLS provides the official CLI tool volclog, supporting automation development and various scenarios. Covering major business domains such as project, log topic, index, query and analysis, alert, consumer group, and data transformation, it provides quick commands, underlying API calls, and some optional features.

volclog is automation-oriented by default, with the main path using contract-first tool / workflow / raw; meanwhile, volclog-human is retained as a manual interaction Shortcut.

Feature	Description
Dual editions	Provides both automation and manual interaction versions, both sharing the same tool / workflow / raw runtime semantics. volclog: Automation edition, prioritized for Agent/CI. volclog-human: Manual interaction Shortcut edition.
Wide business coverage	Covering domains such as project, log topic, index, query and analysis, alert, host group, collection rule, ETL, and consumer group.
Comprehensive security assurance	Provides --dry-run, structured envelope, trace artifacts, and file delivery, making pre-checks, validation, and recovery more straightforward.
Flexible credential access	Provides local profile, explicit region/endpoint, environment variables, and one-time --secrets-file injection.
Layered usage	By default, starts from tool / workflow / raw. Only enter the manual interaction layer of volclog-human when explicitly required.

Core capabilities

The core capabilities supported by the TLS CLI tool are as follows:

Feature	Description
Log project (Project)	Create, query, modify, and delete projects.
Log topic (Topic)	Create, query, modify, and delete topics, and manage the log lifecycle.
Index & query	Create and manage indexes, provide log query capabilities, export SQL analysis, and download raw logs.
Metric topic	Create metric topics and support monitoring metric queries based on PromQL.
Alarm and notification	Configure alarm policies and notification channels to ensure that business exceptions are notified within seconds.
Dashboard	Create and manage visual dashboards for real-time insights into data changes.
Consumer and shipper	Manage consumer groups and configure log shipping to external storage (such as TOS, Kafka, and more).
Data transformation	Log cleansing, enrichment, distribution, and formatting.
Host group and collector	Manage TLS host groups, configure and distribute LogCollector collection rules.
Permission management	Supports accessing TLS via multiple authentication methods. AK/SK long-term credentials STS short-term credentials

Limits

Category	Requirements
Operating system and architecture	Supports Linux, macOS, and Windows. Architecture must be amd64/x86_64 or arm64/aarch64.
Installation dependencies	Binary installation does not require Node.js. NPM installation requires Node.js >= 18, and the installation environment must be able to access GitHub Release.
Credentials and configuration	Ensure network connectivity with the target TLS. Obtain the AccessKey ID and AccessKey Secret for your Volcengine account. Obtain the Region and endpoint information for the target TLS. Notice Dynamically obtain Volcengine credentials and other authentication information through environment variables to avoid data security risks from hardcoding the AccessKey. This can be done through profile, environment variables, --secrets-file, and other approaches.
Large result output	For automation or sandbox environments, it is recommended to prepare a writable directory in advance and explicitly use --output-mode file --output-dir for large queries.

Reference

Permission management:

Describes how to apply for temporary security tokens via the Security Token Service (STS), enabling specified IAM users to access TLS resources within their permission scopes for a designated period of time.

TLS CLI parameter guide:

Describes the relevant rules of volclog, including global parameters, input/output conventions, filtering and error reading, diagnostics and retrospective analysis, common stability rules, as well as credential injection and multi-account isolation methods of use.

TLS CLI manual interaction Shortcut:

Describes common Shortcut commands for volclog-human, including when to use Shortcut and typical usage scenarios in TLS.

TLS CLI practical guidance:

Describes the most common practical workflows for volclog in TLS, including how to ingest log data, troubleshoot issues, export raw logs, and how to help the Agent avoid unnecessary detours. Through three scenarios, demonstrates how to install, configure, and use the CLI tool, and handle real business cases.

Scenarios			Trace analysis
Scenario 1	How to integrate a new project into TLS and complete query and analysis.	Confirm the project. Create a log topic. Configure an index for the topic. Create a collection rule. Bind a host group. Verify log query.
Scenario 2	How to export problematic log data and view visual analysis results.	Quickly query by specifying a time range and query conditions. View log samples matched by the query. View query time distribution. Export raw log samples. Export aggregated results from query and analysis.
Scenario 3	How to troubleshoot when log configuration is complete but logs cannot be collected.	Query the host group list. Query the target collection rule. Query the binding relationship between host groups and collection rules. Modify the binding relationship between host groups and collection rules. Clean up invalid hosts. Verify log collection.

Last updated: 2026.07.21 17:40:56