README

火山引擎 TLS（日志服务）PHP SDK，封装了 TLS OpenAPI 的常用接口，支持日志写入、检索、消费、项目管理等功能，并提供 Monolog 处理器集成。

环境要求

PHP >= 8.2
ext-json

安装

composer require larva/volcengine-tls-sdk-php

快速开始

use Larva\Volc\TlsClient;

$client = new TlsClient(
    $ak,       // Access Key
    $sk,       // Secret Key
    'https://tls-cn-beijing.volces.com', // 接入点地址
    'cn-beijing' // 地域
);

// 批量写入日志
$logs = [
    ['id' => 1, 'content' => 'hello'],
    ['id' => 2, 'content' => 'world'],
];
$response = $client->putLogs('your-topic-id', $logs);

接入点地址

地域	公网接入点
华北2（北京）	`https://tls-cn-beijing.volces.com`
华东1（上海）	`https://tls-cn-shanghai.volces.com`
华南1（广州）	`https://tls-cn-guangzhou.volces.com`

内网接入点将 volces.com 替换为 ivolces.com 即可，SDK 会自动识别公网/内网环境。

API 方法

项目管理

// 创建日志项目
$client->createProject('my-project', 'cn-beijing', '项目描述');

// 查询项目信息
$client->describeProject('project-id');

// 查询所有项目
$client->describeProjects(['PageSize' => 20, 'PageNumber' => 1]);

// 修改项目
$client->modifyProject('project-id', 'new-name', '新描述');

// 删除项目
$client->deleteProject('project-id');

日志写入

// 批量写入
$client->putLogs('topic-id', [
    ['level' => 'info', 'message' => '日志内容'],
    ['level' => 'error', 'message' => '错误信息'],
]);

// 写入单条
$client->putLog('topic-id', ['level' => 'info', 'message' => '单条日志']);

日志检索

// 检索日志
// 文档: https://www.volcengine.com/docs/6470/112195
$response = $client->searchLogs([
    'TopicId' => 'topic-id',
    'Query' => '*',
    'StartTime' => strtotime('-1 hour'),
    'EndTime' => time(),
    'Limit' => 20,
]);

日志消费

// 获取游标
$cursor = $client->describeCursor('topic-id', 0);

// 消费日志（支持 lz4、zlib 压缩）
$result = $client->consumeLogs('topic-id', 0, 0, 'lz4');

分区管理

// 获取分区列表
$client->describeShards('topic-id', 1, 20);

// 手动分裂分区
$client->manualShardSplit('topic-id', 0, 2);

日志下载

// 创建下载任务
$client->createDownloadTask([
    'TopicId' => 'topic-id',
    'Query' => '*',
    'StartTime' => strtotime('-1 day'),
    'EndTime' => time(),
]);

// 查询下载任务列表
$client->describeDownloadTasks('topic-id', '', 1, 20);

// 获取下载链接
$client->describeDownloadUrl('task-id');

// 取消下载任务
$client->cancelDownloadTask('task-id');

Kafka 消费配置

通过 Kafka 协议消费日志，SDK 可直接生成连接配置：

$config = $client->getKafkaConfig('project-id', 'topic-id');
// 返回:
// [
//     'host' => 'tls-cn-beijing.volces.com:9093',
//     'username' => 'project-id#public',  // 内网为 #private
//     'password' => 'ak#sk',
//     'topic' => 'out-topic-id',
// ]

Monolog 集成

SDK 提供了 Monolog 处理器，可直接将应用日志推送到 TLS。

Monolog 3.x（Laravel 10+ / PHP 8.2+）

use Larva\Volc\MonologHandler;
use Larva\Volc\TlsLoggingFormatter;
use Monolog\Logger;

$handler = new MonologHandler(
    $ak,
    $sk,
    'https://tls-cn-beijing.volces.com',
    'topic-id',
    'cn-beijing'
);
$handler->setFormatter(new TlsLoggingFormatter());

$logger = new Logger('tls');
$logger->pushHandler($handler);

$logger->info('Hello TLS', ['user_id' => 123]);

Monolog 2.x

use Larva\Volc\MonologHandler2;
use Larva\Volc\TlsLoggingFormatter2;
use Monolog\Logger;

$handler = new MonologHandler2(
    $ak,
    $sk,
    'https://tls-cn-beijing.volces.com',
    'topic-id',
    'cn-beijing'
);
$handler->setFormatter(new TlsLoggingFormatter2());

$logger = new Logger('tls');
$logger->pushHandler($handler);

Laravel 集成

在 config/logging.php 中添加自定义 channel：

'tls' => [
    'driver' => 'custom',
    'via' => function ($config) {
        $handler = new \Larva\Volc\MonologHandler(
            env('TLS_AK'),
            env('TLS_SK'),
            env('TLS_ENDPOINT', 'https://tls-cn-beijing.volces.com'),
            env('TLS_TOPIC_ID'),
            env('TLS_REGION', 'cn-beijing')
        );
        $handler->setFormatter(new \Larva\Volc\TlsLoggingFormatter());

        return tap(new \Monolog\Logger('tls'), function ($logger) use ($handler) {
            $logger->pushHandler($handler);
        });
    },
],

.env 配置：

TLS_AK=your-access-key
TLS_SK=your-secret-key
TLS_ENDPOINT=https://tls-cn-beijing.volces.com
TLS_TOPIC_ID=your-topic-id
TLS_REGION=cn-beijing

关于实时日志导入

实时日志导入使用 putLogs 接口并非最佳选择，因为每次请求都会建立 HTTP 连接，开销较大。建议：

高频写入：使用 Kafka 协议或 Socket 方式直接写入日志（SDK 的 getKafkaConfig 方法可生成 Kafka 连接配置）
批量导入：使用 putLogs 批量写入，适合小项目或日志归档场景
查询分析：使用 searchLogs 进行日志检索和统计分析

License

MIT

larva / volcengine-tls-sdk-php

Maintainers

Package info

Statistics

Security