agent.md

Creating an Agent

You will need to create an Agent object to manage events and send data to APM. A valid Config object must be provided during Agent creation.

Creation with AgentBuilder::create()

The static AgentBuilder::create() method is the easiest approach if you only need to pass some configuration values to Agent.

$agent = AgentBuilder::create(['serviceName' => 'My Application']);

The create method only accepts an array of valid configuration options. For more advanced Agent constructions, you must use the various AgentBuilder object methods.

Creation with AgentBuilder Object Methods

The AgentBuilder class provides methods to create a configured Agent. The basic usage is:

$builder = new \Nipwaayoni\AgentBuilder();
$builder->withConfig(new Nipwaayoni\Config([]));
$agent = $builder->build();

The following methods are available to influence the Agent creation:

$builder->withConfigData(array $config);
$builder->withConfig(Config $config);
$builder->withUserContextData(array $context);
$builder->withCustomContextData(array $context);
$builder->withTagData(array $tags);
$builder->withEnvData(array $env);
$builder->withCookieData(array $cookies);
$builder->withEventFactory(EventFactoryInterface $eventFactory);
$builder->withTransactionStore(TransactionsStore $store);
$builder->withHttpClient(ClientInterface $httpClient);
$builder->withRequestFactory(RequestFactoryInterface $requestFactory);
$builder->withStreamFactory(StreamFactoryInterface $streamFactory);

All of the with methods support fluent chaining. See the agent example for more information.

Note 1: The methods ending with Data take an array and will eventually have companion methods that take an object. (See the withConfigData() and withConfig() methods for example.) The Data methods will be deprecated when objects are available.

Note 2: Previous versions of the Agent accepted an array of key/value pairs as the second argument to the constructor. These were used as the "shared context". Those contexts have been split into specific with methods for clarity. The values are unchanged, simply use the appropriate method corresponding to the array key used previously.

This approach to building the Agent allows developers to easily inject desired values/implementation without concern for the long list of constructor arguments. For maintainers, we will be able to change the Agent creation without causing major disruption to current consumers.

Hooking the APM Request in the AgentBuilder

You can set pre and post hooks for the HTTP request used to send transaction event data to APM.

$builder->withPreCommitCallback(callable $callback);
$builder->withPostCommitCallback(callable $callback);

Your callbacks should expect to be called as below and should not return a value.

$builder->withPreCommitCallback(function (RequestInterface $request) {
        // Request stuff
    });

$builder->withPostCommitCallback(function (ResponseInterface $response) {
        // Response stuff
    });

The primary purpose of these hooks is to enable logging or other diagnostics of the APM request/response.

Creation Through Direct Instantiation (Deprecated)

An Agent object can created directly if necessary. Note that the constructor parameters have changed and are also now required. The Agent now relies on the caller to provide component implementations. We strongly recommend using the AgentBuilder for this purpose. The following example shows how to create an Agent:

$agent = new \Nipwaayoni\Agent(
    new Nipwaayoni\Config(...), 
    new \Nipwaayoni\Contexts\ContextCollection(...),
    new \Nipwaayoni\Middleware\Connector(...),
    new \Nipwaayoni\Events\DefaultEventFactory(),
    new \Nipwaayoni\Stores\TransactionsStore()
);

Extending the Agent Class

You can add your own agent functionality by extending the Agent class.

When you extend the Agent class, you should override the NAME and VERSION class constants as appropriate for your class.

Using your own Agent implementation will likely require also extending the AgentBuilder class, as described below. The Agent requires a number of supporting objects to function which the AgentBuilder helps to construct.

Extending the AgentBuilder Class

You should also extend the AgentBuilder when you extend the Agent class. While it is possible to take full responsibility for creating your Agent object, the base class requires a number of configured objects to function. The builder calls the AgentBuilder::newAgent() method and returns the result as the constructed Agent object. You can override that method to create your own object. The builder will call the method with all of the objects necessary to pass to Agent::__construct():

class MyAgentBuilder extends AgentBuilder 
{
    ...
    protected function newAgent(Config $config,
                                ContextCollection $sharedContext,
                                Connector $connector,
                                EventFactoryInterface $eventFactory,
                                TransactionsStore $transactionsStore)
    {
        $otherOption = ''; #get a value somewhere

        return new MyAgent(
            $config,
            $sharedContext,
            $connector,
            $eventFactory,
            $transactionsStore,
            $otherOption
        );
    }
    ...
}

class MyAgent extends Agent
{
    ...
    public function __construct(
        Config $config,
        ContextCollection $sharedContext,
        Connector $connector,
        EventFactoryInterface $eventFactory,
        TransactionsStore $transactionsStore,
        int $otherOption
    ) {
        parent::__construct($config, $sharedContext, $connector, $eventFactory, $transactionsStore);
        
        $this->otherOption = $otherOption;
    }
    ...
}