README

版本 1.0

PHP Splunk 软件开发工具包 (SDK) 使得 PHP 应用程序能够轻松地与 Splunk 服务器进行通信和控制。使用 SDK 提供的 API，应用程序可以启动搜索、显示结果以及执行管理任务。

关于 Splunk

Splunk 是一种搜索引擎和数据分析环境，它使用分布式 MapReduce 架构来高效地索引、搜索和处理大量变化的数据集。

Splunk 产品在系统管理员中很受欢迎，用于 IT 机器数据的聚合和监控、安全、合规以及各种其他场景，这些场景都需要高效地对大量时间序列数据进行索引、搜索、分析和实时通知。

许可证

PHP Splunk 软件开发工具包在 Apache License 2.0 许可下发布。详细信息可在文件 LICENSE 中找到。

要求

SDK 需要 PHP 5.2.11 或更高版本以及 SimpleXML 扩展。强烈推荐使用 PHP 5.3.7 或更高版本。

要访问 Splunk 的 https:// URLs，需要 PHP 的 OpenSSL 支持。

如果您使用的是 PHP 5.3.6 或更早版本，还需要 cURL 扩展。在此配置下，SDK 在通过 https:// URLs 访问 Splunk 时将不支持流式传输大量结果。

入门指南

如果您尚未安装 Splunk，请从这里下载：http://www.splunk.com/download。

有关安装和运行 Splunk 以及系统要求的更多信息，请参阅安装 & 运行 Splunk。

通过 git 克隆存储库从 GitHub 获取 PHP Splunk SDK 的副本。

git clone https://github.com/splunk/splunk-sdk-php.git

SDK 布局

示例

要运行示例，您需要在本地安装一个支持 PHP 的 Web 服务器。

在 Mac OS X 上，推荐使用 MAMP。
在 Windows 上，推荐使用 XAMPP。您还需要配置 PHP 以支持 OpenSSL。
- 打开 C:\xampp\php\php.ini。
- 找到行 ;extension=php_openssl.dll 并删除前面的分号 (;)。
- 如果 Apache 已经正在运行，请使用 XAMPP 控制面板重新启动 Apache。
在 Linux 上，从您的包管理器安装 Apache 和 PHP。

然后，将整个 splunk-sdk-php 目录（包含 examples 和 Splunk.php）移动到您的 Web 服务器文档根目录中。

对于 MAMP，文档根位于：/Applications/MAMP/htdocs/
对于 XAMPP，文档根位于：C:\xampp\htdocs\

最后，将 examples 目录中的 settings.default.php 复制一份，重命名为 settings.local.php，然后编辑该文件。取消注释 'port'、'username' 和 'password' 字段，并使用您的 Splunk 服务器凭据更新文件。

您应该能够通过类似以下 URL 访问 SDK 示例

https://:8888/splunk-sdk-php/examples/index.php

（您可能需要根据您的 Web 服务器更改 URL 的端口号，例如 8080 或 80）

如果您看到类似以下错误

Login Failed.
Reason: fopen(https://:8089/services/auth/login): failed to open stream: Invalid argument

这表示您需要在 PHP 配置（php.ini）中启用 OpenSSL 支持。

单元测试

要求

PHPUnit 3.6 或更高版本
Xdebug 2.0.5或更高版本（用于代码覆盖率）
在tests目录中复制settings.default.php，将其重命名为settings.local.php，然后编辑该文件。取消注释'port'、'username'和'password'字段，并使用为测试保留的Splunk服务器的凭据更新文件。

要执行所有单元测试，运行

phpunit tests

要仅执行快速单元测试，运行

phpunit --exclude-group slow tests

要生成代码覆盖率报告，运行

phpunit --coverage-html coverage tests
open coverage/Splunk.html

API文档

要求

phpDocumentor 2
GraphViz（可选）
- 使用命令行工具dot在文档中渲染类层次结构图

要生成API文档，运行

phpdoc -d Splunk -t apidocs

变更日志

您可以在此处查看每个版本的变更日志。

快速入门

PHP SDK提供了一种面向对象的接口，用于与Splunk服务器交互。

要使用SDK，首先导入Splunk.php。这将使您能够访问所有Splunk_*类。

require_once 'Splunk.php';

然后使用Splunk_Service的实例连接到Splunk服务器。

$service = new Splunk_Service(array(
    'host' => 'localhost',
    'port' => '8089',
    'username' => 'admin',
    'password' => 'changeme',
));
$service->login();

连接后，您可以操作服务器上的各种实体，例如已保存的搜索和搜索作业。

例如，以下代码执行快速搜索并打印结果。

// NOTE: The expression must begin with 'search ' or '| '
$searchExpression = 'search index=_internal | head 100 | top sourcetype';

// Create oneshot search and get results
$resultsXmlString = $service->getJobs()->createOneshot($searchExpression);
$results = new Splunk_ResultsReader($resultsXmlString);

// Process results
foreach ($results as $result)
{
    if ($result instanceof Splunk_ResultsFieldOrder)
    {
        // Process the field order
        print "FIELDS: " . implode(',', $result->getFieldNames()) . "\r\n";
    }
    else if ($result instanceof Splunk_ResultsMessage)
    {
        // Process a message
        print "[{$result->getType()}] {$result->getText()}\r\n";
    }
    else if (is_array($result))
    {
        // Process a row
        print "{\r\n";
        foreach ($result as $key => $valueOrValues)
        {
            if (is_array($valueOrValues))
            {
                $values = $valueOrValues;
                $valuesString = implode(',', $values);
                print "  {$key} => [{$valuesString}]\r\n";
            }
            else
            {
                $value = $valueOrValues;
                print "  {$key} => {$value}\r\n";
            }
        }
        print "}\r\n";
    }
    else
    {
        // Ignore unknown result type
    }
}

核心概念

实体和集合

实体是Splunk服务器上的一个对象。这包括已保存的搜索、搜索作业、索引、输入等。

每种类型的实体都位于一个集合中。可以在Splunk_Service对象上访问每种集合类型。

例如，要检索已保存的搜索或搜索作业的列表

$savedSearches = $service->getSavedSearches()->items();  // in the default namespace
$jobs = $service->getJobs()->items();                    // in the default namespace

您还可以通过名称检索集合中的特定实体

$topSourcetypesSearch = $service->getSavedSearches()->get('Top five sourcetypes');

命名空间

实体有一个命名空间，这与实体的访问权限相对应。

所有检索单个实体或实体列表的函数都可以提供一个命名空间参数。（如果您省略此参数，则将使用Splunk_Service的默认命名空间。）

例如，要检索search应用中用户admin拥有的已保存搜索的列表

$savedSearches = $service->getSavedSearches()->items(array(
	'namespace' => Splunk_Namespace::createUser('admin', 'search'),
));

或，要检索命名空间中的单个实体

$topSourcetypesSearch = $service->getSavedSearches()->get(
	'Top five sourcetypes',
	Splunk_Namespace::createApp('search'));

如果您通常在同一个命名空间中访问许多对象，可以将默认命名空间传递给Splunk_Service构造函数。这允许您在每次调用get()或items()时避免传递显式的命名空间。

$service = new Splunk_Service(array(
    ...
    'namespace' => Splunk_Namespace::createUser('admin', 'search'),
));
$service->login();

$jobs = $service->getJobs()->items();			// in the admin/search namespace
$indexes = $service->getIndexes()->items(array(	// in the system namespace
	'namespace' => Splunk_Namespace::createSystem(),
));

命名空间类型在此处描述

常见任务

使用搜索表达式运行搜索

一次性搜索

对于运行快速且结果数量较少的搜索，最简单的方法是创建一个一次性搜索

// NOTE: The expression must begin with 'search ' or '| '
$searchExpression = 'search index=_internal | head 100 | top sourcetype';

// Create oneshot search and get results
$resultsXmlString = $service->getJobs()->createOneshot($searchExpression);
$results = new Splunk_ResultsReader($resultsXmlString);

// Process results
foreach ($results as $result)
{
    if ($result instanceof Splunk_ResultsFieldOrder)
    {
        // Process the field order
        // ...
    }
    else if ($result instanceof Splunk_ResultsMessage)
    {
        // Process a message
        print "[{$result->getType()}] {$result->getText()}\r\n";
    }
	else if (is_array($result))
    {
        // Process a row
        foreach ($result as $key => $valueOrValues)
        {
            // ...
        }
    }
    else
    {
        // Ignore unknown result type
    }
}

一次性搜索会阻塞直到完成，并立即返回所有结果。

阻塞搜索作业

对于返回大量结果且不需要监控进度的搜索，最简单的方法是创建一个阻塞搜索作业

// NOTE: The expression must begin with 'search ' or '| '
$searchExpression = 'search index=_internal | head 1000';

// Create blocking search job and get results
$job = $service->getJobs()->create($searchExpression, array(
	'exec_mode' => 'blocking',
));
$results = $job->getResults();

// Process results
...

阻塞搜索作业会等待直到所有结果都可用。

异步（正常）搜索作业

对于可能返回大量结果的搜索，应创建一个异步（正常）搜索作业。

异步作业允许您在它们运行时监控它们的进度。

// NOTE: The expression must begin with 'search ' or '| '
$searchExpression = 'search index=_internal | head 10000';

// Create normal search job
$job = $service->getJobs()->create($searchExpression);

// Wait for job to complete and get results
while (!$job->isDone())
{
	printf("Progress: %03.1f%%\r\n", $job->getProgress() * 100);
	usleep(0.5 * 1000000);
	$job->refresh();
}
$results = $job->getResults();

// Process results
...

运行已保存的搜索

您可以通过在Splunk_SavedSearch对象上调用dispatch()方法，根据已保存的搜索创建一个正常搜索作业。

$savedSearch = $service->getSavedSearches()->get('Top five sourcetypes');

// Create normal search job based on the saved search
$job = $savedSearch->dispatch();

// Wait for job to complete and get results
...

// Process results
...

运行实时搜索

实时搜索必须作为异步搜索作业运行。阻塞和一次性模式都不适用，因为实时搜索永远不会真正完成。

要从实时搜索中获取结果，必须使用getResultsPreviewPage()方法而不是getResults()方法。

资源

您可以在Splunk开发者门户中找到与Splunk开发相关的一切。

对于所有与Splunk相关的开发内容，您的主要资源是Splunk开发者门户。
有关概念和操作文档，请参阅Splunk SDK for PHP概述。
有关API参考文档，请参阅Splunk SDK for PHP参考
有关Splunk REST API的更多信息，请参阅REST API参考。
有关Splunk的一般信息，请参阅Splunk>Docs。
有关此SDK存储库的更多信息，请参阅我们的GitHub Wiki。

社区

与其他基于Splunk进行开发的开发者保持联系。

如何贡献

如果您想为SDK做出贡献，请按照以下提供的链接之一进行操作。

支持

如果您或您的公司已经在一个现有的维护/支持协议下，您将获得支持。访问http://www.splunk.com/support，并在“联系支持工程师”下点击“提交案例”。
如果您不在现有的维护/支持协议下，您可以通过更广泛的社区找到帮助
- Splunk Answers（使用sdk和php标签来识别您的问题）
- Splunkdev Google Group
Splunk将不会支持已修改核心库（位于splunk目录中的代码）的SDK。如果您修改了SDK并需要支持，您可以通过更广泛的社区和Splunk答案（见上文）来找到帮助。我们还想了解您修改核心库的原因——请将反馈发送至devinfo@splunk.com。
在GitHub上提交任何问题。

联系我们

您可以通过devinfo@splunk.com联系开发平台团队。

gtunes / splunk

维护者

详细信息