README

使用我们的在线监控将 Tethered 集成到您的 PHP 项目中。

您可以发送自定义指标，内部记录在线时长并创建事件。

要求

在开始之前，您需要一个 Tethered 账户，并在您的 账户信息 中找到您的 API 密钥。

您还需要一个监控设置，因为这是同步调用的要求。这可以通过辅助方法进行更改，但在大多数情况下，您的服务器将与特定的监控 ID 链接。

包含

如果您正在使用 Composer，我们的库应该可以从 Packagist 获取，并且可以通过在您的 composer.json 中添加对我们的模块的依赖来安装

{
  "require": {
      "codecabin/tethered-uptime-php": "*"
  }
}

然后，使用以下命令安装依赖项

php composer.phar install

然后，当您包含供应商自动加载器时，我们的模块将自动加载

require_once __DIR__ . '/vendor/autoload.php';

或者，如果您愿意，可以使用单个命令执行安装

php composer.phar require codecabin/tethered-uptime-php:*

如果您不使用 composer 作为依赖项管理器，您也可以下载此项目并通常加载文件

require_once(__DIR__ . '/tethered-uptime-php/src/class.tethered-uptime.php');

为了便于使用，您还可以使用我们的命名空间来简化声明

use CodeCabin\TetheredUptime;

对于剩余的示例，我们将假设您已经将其包含在项目中。

基本用法

如果您想自动发送系统指标以及在线时长，这只需几行代码即可实现

$uptime = new TetheredUptime(
    (object) array(
        'apikey' => '[APIKEY]', 
        'monitorId' => 1,
    )
);

对于 PHP，我们无法在程序性 cronjob 上自动运行同步逻辑，因此您需要管理同步调用发生的频率。通常，您会设置自己的 cronjob 并在那里初始化此实例，以定义的频率调用同步

$uptime->sync();

配置选项

作为模块构造函数的一部分，您可以通过 基本用法 示例中所示的方式传递配置对象

$uptime = new TetheredUptime($configuration);

此对象支持许多选项，您可以使用这些选项来更改模块的行为方式。

常量

让我们看看您可以在配置中使用的每个可用常量。

修饰符

使用修饰符来修改发送到 Tethered 的数据可能很有帮助，例如，如果您想发送额外的资源统计信息，但又想优化对 API 的使用（其中有些速率限制），或者只是想每当您调用 'sync' 方法时都包含此数据。

让我们看看如何挂钩到在 'sync' 上发送的指标列表，以包含您自己的数据

$uptime = new TetheredUptime(
    (object) array(
        'apikey' => '[APIKEY]', 
        'monitorId' => 1,
        'modifiers' => (object) array(
            'metrics.list' => array(
                function($list) {
                    $list[] = (object) array(
                        'key' => 'custom.metric',
                        'value' => 5,
                        'label' => 'Custom Metric',
                        'type' => 'percentage',
                        'widget' => 'pie'
                    );

                    return $list;
                }
            )
        )
    )
);

$uptime->sync();

还有另一种应用修饰符的方法，类似于其他基于挂钩的系统

$uptime = new TetheredUptime($configuration);

$uptime->addModifier('status.code', function($code){
    return $code * 2;
});

$uptime->sync();

可用的修饰符

以下是目前可用的修饰符列表，以及这些修饰符将传递的参数类型。这些可能会随着时间的推移而扩展。

事件

事件是观察模块中事件分发时的另一种方式。与修饰符不同，我们的模块不等待或期望任何响应，这意味着这是一个单向事件。

这些可以通过两种方式注册，与修饰符的方式相同，因此我们现在将查看这两种方式。

首先，让我们通过将我们的监听器直接添加到配置对象中来监听 'sync' 事件。

$uptime = new TetheredUptime((object) array(
    'apikey' => '[APIKEY]', 
    'monitorId' => 1,
    'events' => (object) array(
        'sync' => array(
            function() {
                echo "Sync has been called";
            }
        )
    )
));

$uptime->sync();

现在我们将查看对特定响应事件的监听，该事件在状态成功记录时运行。这还包括响应对象，为了演示目的，我们将在初始化后注册此监听器。

$uptime = new TetheredUptime($configuration);

$uptime->listen('status.complete', function($response){
    echo "Response was received: <br>";
    var_dump($response);
});

$uptime->sync();

可用事件

以下是我们可用的事件的列表，包括它将发送的数据类型（如果有）。这些可能会随着时间的推移而扩展。

方法

以下部分将介绍模块中所有可用的方法。其中一些是专门为内部使用而设计的，因此不会进行演示，因为这些调用不建议使用。

configure($config)

配置模块，作为构造函数调用的部分。配置对象与内部默认配置同步，并注册任何传入的修饰符和事件监听器。

setMonitor($id)

允许您在初始化后调整活动目标监控器，如果需要多监控管理。

$uptime = new TetheredUptime($configuration);

// Set active monitor to ID 2
$uptime->setMonitor(2);

sync()

自动将所有数据发送到服务器，由 $configuration->syncFlags 控制，通常是状态和指标。这应该在您控制的一些事件中调用，例如每小时运行一次的cronjob。

$uptime = new TetheredUptime($configuration);

// Trigger the sync event
$uptime->sync();

pushStatus($code, $time)

将新的状态代码推送到您的活动监控器的API。这会自动由sync()方法调用，但在需要时也可以手动调用。

如有需要，返回底层请求的结果。

$uptime = new TetheredUptime($configuration);

// Send status code 403 with timing of 112ms
$response = $uptime->pushStatus(403, 112);

pushMetric($key, $value, $label = "", $type = "", $widget = "")

将单个指标推送到您的活动监控器的API。这不会自动调用，因为我们使用的是pushMetrics()方法，该方法获取系统的快照。

如有需要，返回底层请求的结果。

$uptime = new TetheredUptime($configuration);

// Log a custom metric (single)
$response = $uptime->pushMetric('custom_metric', 5, 'Custom Metric', 'percentage', 'pie');

pushMetrics()

使用快照方法将所有指标（由 $configuration->metricFlags 控制）推送到API。这会自动由sync方法调用，但在需要时也可以手动调用。

需要向此批量推送添加自定义指标？请查看修饰符。

如有需要，返回底层请求的结果。

$uptime = new TetheredUptime($configuration);

// Log all metrics (all)
$response = $uptime->pushMetrics();

getMonitors()

从API获取您的完整监控器列表。这不是自动调用的，是您需要时使用的辅助工具。结果不进行分页，请记住这一点。

返回底层请求的结果，其中包含您的监控器。

$uptime = new TetheredUptime($configuration);

// Get monitors
$monitors = $uptime->getMonitors();

getIncidents($page = 1)

获取与您的帐户相关联的事件。这不是自动调用的，是您需要时使用的辅助工具。结果进行分页。

返回底层请求的结果，包含所选页面的事件。

$uptime = new TetheredUptime($configuration);

// Get incidents
$incidents = $uptime->getIncidents();

pushIncident($title, $description, $source = false, $status = 0)

创建与您的帐户相关联的新事件，这将与您的活动监控器相关联。这不是自动调用的，是您需要时使用的。

如有需要，返回底层请求的结果。

$uptime = new TetheredUptime($configuration);

// Create an incident
$response = $uptime->pushIncident("Server issue", "PHP server is experiencing issues, with these details...", "PHP Server", 0);

snapshot()

获取系统资源的快照。如果在同步指标时调用sync，则会调用此方法。

$uptime = new TetheredUptime($configuration);

// Get resource snapshot
$snapshot = $uptime->snapshot();

addModifier($tag, $callable)

将修饰符添加到修饰符列表中，与特定标签（钩子）相关联，并具有可调用的函数。

$uptime = new TetheredUptime($configuration);

// Add a modifier
$uptime->addModifier('status.code', function($code){
    $code = 403;
    return $code;
});

applyModifiers($tag, $data)

在实例中应用修饰符，这将调用标签并遍历任何链接的可调用项（链式），允许每个它们修改数据，然后在返回最终样本之前将其返回到模块中使用。

这是一个内部方法，我们不建议在模块外部使用它，因为它是为内部使用而设计的，但从理论上讲是可能的。

listen($tag, $callable)

向模块添加事件监听器，与特定标签（钩子）相关联，并具有可调用的函数。

$uptime = new TetheredUptime($configuration);

// Add a listener
$uptime->listen('ready', function() {
    echo "scheduler is running";
});

trigger($tag, $data)

在实例中触发事件，这将调用标签并遍历任何链接的可调用项，并通过函数调用发送任何数据包。这是一个单向事件，您不能返回任何数据。

这是一个内部方法，我们不建议在模块外部使用它，因为它是为内部使用而设计的，但从理论上讲是可能的。

get($endpoint, $data)

使用所需API的端点和数据向我们的API执行GET请求。

这将返回请求响应，可以用于执行任何助手方法不支持的其他API调用。

请记住，在直接调用时，您需要将API密钥作为数据的一部分传递。

$uptime = new TetheredUptime($configuration);

$data = (object) array(
    "apikey" => $uptime->configuration->apikey
);

// Get notifiers linked to your account
$response = $uptime->get('/notifiers');

post($endpoint, $data)

使用API所需的端点和数据向我们的API执行POST请求。

这将返回请求响应，可以用于执行任何助手方法不支持的其他API调用。

请记住，在直接调用时，您需要将API密钥作为数据的一部分传递。

$uptime = new TetheredUptime($configuration);

$data = (object) array(
    "apikey" => $uptime->configuration->apikey,
    /* Additional fields required and specified by API */
);

// Create notifier linked to your account
$response = $uptime->post('/notifier');

delete(endpoint, data)

使用API所需的端点和数据向我们的API执行DELETE请求。

这将返回请求响应，可以用于执行任何助手方法不支持的其他API调用。

请记住，在直接调用时，您需要将API密钥作为数据的一部分传递。

$uptime = new TetheredUptime($configuration);

$data = (object) array(
    "apikey" => $uptime->configuration->apikey,
    "id" => 1
);

// Delete notifier linked to your account
$response = $uptime->delete('/notifier');

request($endpoint, $data, $method)

最终请求方法，仅用于内部使用，实际上在将请求发送到API之前编译请求。

您应该使用get、post或delete而不是直接调用此方法。

API

请记住，只要您有权访问该特定功能且在您的使用限制内，您就可以使用get、post和delete方法调用我们的任何API端点，这意味着如果这是您需要的，此模块几乎可以实现完全的账户自动化。

您需要对我们的API有一个相当全面的理解，但您可以在我们的开发者文档中了解更多信息。