Skip to content

Commit 11e64d7

Browse files
alexandergullalexandergull
authored
Merge pull request #875 from CleanTalk/integration-metrics.ag
New. Code. Integrations performance base metrics.
2 parents 3ca367f + 3840764 commit 11e64d7

13 files changed

Lines changed: 1406 additions & 7 deletions

File tree

‎lib/Cleantalk/Antispam/IntegrationMetrics/IMetricDTO.php‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
<?php
2+
3+
namespace Cleantalk\Antispam\IntegrationMetrics;
4+
5+
/**
6+
* Integration Metrics Data Transfer Object
7+
*
8+
* This class captures performance metrics for integration processing, including execution time,
9+
* memory usage, and custom performance data. It acts as a container for performance telemetry
10+
* that can be serialized to JSON for transmission to monitoring/analytics systems.
11+
*
12+
* The class is designed to work with IMetricService which handles metric collection and
13+
* span lifecycle management (creation, measurement, finalization).
14+
*
15+
* Usage Example:
16+
* <code>
17+
* $dto = new IMetricDTO();
18+
* $dto->integration_name = 'WooCommerce';
19+
* $dto->custom_fields['order_count'] = 5;
20+
*
21+
* $json = $dto->getJSON();
22+
* // Send $json to analytics backend
23+
* </code>
24+
*
25+
* @see IMetricService for metric lifecycle management
26+
* @see IMetricDTOTrait for integration with IntegrationBase and IntegrationByClassBase
27+
*/
28+
class IMetricDTO
29+
{
30+
/**
31+
* Name of the integration being measured (e.g., 'WooCommerce', 'NinjaForms').
32+
* Set by IMetricService::getDTO() when creating a new DTO instance.
33+
*
34+
* @var string
35+
* @psalm-suppress PossiblyUnusedProperty
36+
*/
37+
public $integration_name = 'unset';
38+
39+
/**
40+
* Version of the metrics schema/format.
41+
* Can be overridden via IMetricDTOTrait::$imetric_dto_version on the integration class.
42+
*
43+
* @var string
44+
* @psalm-suppress PossiblyUnusedProperty
45+
*/
46+
public $dto_version = '1.0.0';
47+
48+
/**
49+
* Peak memory usage difference in kilobytes (KB) during integration processing.
50+
* Calculated as: peak_memory_at_end - peak_memory_on_start
51+
* Set during IMetricService::finalizeDTO()
52+
*
53+
* @var int
54+
* @psalm-suppress PossiblyUnusedProperty
55+
*/
56+
public $peak_memory_diff_kb = 0;
57+
58+
/**
59+
* Total execution time in milliseconds (ms) for the entire integration processing.
60+
* Calculated as: end_time_ms - timer_on_start_msec
61+
* Set during IMetricService::finalizeDTO()
62+
*
63+
* @var int
64+
* @psalm-suppress PossiblyUnusedProperty
65+
*/
66+
public $total_exec_time_ms = 0;
67+
68+
/**
69+
* Custom performance fields added by the integration.
70+
* Format: field_name => field_value
71+
* Example: ['form_fields_count' => 15, 'validation_passed' => true]
72+
* Populated via IMetricService::setCustomField()
73+
*
74+
* @var array
75+
* @psalm-suppress PossiblyUnusedProperty
76+
*/
77+
public $custom_fields = array();
78+
79+
/**
80+
* Named time spans tracking specific operations within the integration.
81+
* Format: span_name => ['time_msec' => float, 'memory_kb' => float, 'memory_peak_kb' => float, 'released' => bool]
82+
*
83+
* Each span captures:
84+
* - time_msec: Duration in milliseconds (calculated by IMetricService::lease())
85+
* - memory_kb: Memory usage in KB (calculated by IMetricService::lease())
86+
* - memory_peak_kb: Peak memory in KB (calculated by IMetricService::lease())
87+
* - released: Whether the span has been finalized (true = measurements complete)
88+
*
89+
* Spans are created via IMetricService::seek() and finalized via IMetricService::lease()
90+
*
91+
* @var array
92+
*/
93+
public $spans = array();
94+
95+
/**
96+
* Peak memory usage in KB for specific variable groups, tracked by span name.
97+
* Format: span_name => peak_kb_value
98+
* Example: ['form_data_vars' => 42.5, 'post_data_vars' => 128.3]
99+
* Populated via IMetricService::dumpVarsSize()
100+
*
101+
* @var array
102+
* @psalm-suppress PossiblyUnusedProperty
103+
*/
104+
public $variable_peak_kb = array();
105+
106+
/**
107+
* Internal: Timer value (in ms) captured at metric start.
108+
* Used to calculate total_exec_time_ms = current_time - timer_on_start_msec
109+
* Set by IMetricService::startGlobalSeeking() and should not be modified directly.
110+
* Excluded from JSON output via getArray()
111+
*
112+
* @var int
113+
*/
114+
public $timer_on_start_msec = 0;
115+
116+
/**
117+
* Internal: Memory usage (in KB) captured at metric start.
118+
* Used to track relative memory usage throughout integration processing.
119+
* Set by IMetricService::startGlobalSeeking() and should not be modified directly.
120+
* Excluded from JSON output via getArray()
121+
*
122+
* @var int
123+
* @psalm-suppress PossiblyUnusedProperty
124+
*/
125+
public $memory_usage_on_start_kb = 0;
126+
127+
/**
128+
* Internal: Peak memory usage (in KB) captured at metric start.
129+
* Used to calculate peak_memory_diff_kb = peak_memory_at_end - peak_memory_on_start_kb
130+
* Set by IMetricService::startGlobalSeeking() and should not be modified directly.
131+
* Excluded from JSON output via getArray()
132+
*
133+
* @var int
134+
*/
135+
public $peak_memory_on_start_kb = 0;
136+
137+
/**
138+
* Internal: Flag indicating whether metric finalization is complete.
139+
* When true, no further span creation or field updates are allowed.
140+
* Set by IMetricService::finalizeDTO()
141+
* Excluded from JSON output via getArray()
142+
*
143+
* @var bool
144+
*/
145+
public $is_released = false;
146+
147+
/**
148+
* JSON key name used when embedding this DTO in sender info.
149+
* Used to identify metric data in analytics payloads.
150+
*
151+
* @var string
152+
*/
153+
public static $SENDER_INFO_KEY = 'imetric';
154+
155+
/**
156+
* Serializes the DTO to JSON string.
157+
*
158+
* Converts the DTO object to a JSON-encoded string suitable for transmission to analytics systems.
159+
* Internally calls getArray() to filter out internal properties before encoding.
160+
*
161+
* @return false|string JSON string representation of the DTO, or false if JSON encoding fails
162+
*
163+
* @see getArray() for the exact properties included in the output
164+
*/
165+
public function getJSON()
166+
{
167+
return @json_encode($this->getArray());
168+
}
169+
170+
/**
171+
* Returns the DTO as an associative array, excluding internal properties.
172+
*
173+
* This method filters out internal tracking properties that are not meant to be transmitted:
174+
* - is_released: tracks finalization state
175+
* - peak_memory_on_start_kb: baseline for calculations
176+
* - memory_usage_on_start_kb: baseline for calculations
177+
* - timer_on_start_msec: baseline for calculations
178+
* - SENDER_INFO_KEY: static metadata key
179+
*
180+
* All other public properties are included in the output array.
181+
*
182+
* Usage:
183+
* <code>
184+
* $dto = new IMetricDTO();
185+
* $dto->integration_name = 'MyForm';
186+
* $dto->custom_fields['status'] = 'success';
187+
*
188+
* $array = $dto->getArray();
189+
* // $array now contains integration_name, dto_version, spans, custom_fields, etc.
190+
* // but not is_released or *_on_start_* properties
191+
* </code>
192+
*
193+
* @return array Associative array of DTO properties ready for JSON serialization
194+
*
195+
* @see getJSON() for JSON-encoded output
196+
*/
197+
public function getArray()
198+
{
199+
$skip_properties = array(
200+
'is_released',
201+
'peak_memory_on_start_kb',
202+
'memory_usage_on_start_kb',
203+
'timer_on_start_msec',
204+
'SENDER_INFO_KEY'
205+
);
206+
return array_map(function ($value) {
207+
return $value;
208+
}, array_diff_key(get_object_vars($this), array_flip($skip_properties)));
209+
}
210+
}

‎lib/Cleantalk/Antispam/IntegrationMetrics/IMetricDTOTrait.php‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
<?php
2+
3+
namespace Cleantalk\Antispam\IntegrationMetrics;
4+
5+
use Cleantalk\ApbctWP\Constant;
6+
7+
/**
8+
* Integration Metrics DTO Trait
9+
*
10+
* Provides metric storage and access methods for integration classes.
11+
* This trait should be used in IntegrationBase and IntegrationByClassBase subclasses
12+
* to enable performance metric collection.
13+
*
14+
* The trait manages:
15+
* - Storage of the IMetricDTO instance
16+
* - Schema version configuration for the metrics
17+
* - Getter/setter methods for safe access
18+
*
19+
* Usage Example:
20+
* <code>
21+
* class MyIntegration extends IntegrationBase {
22+
* use IMetricDTOTrait; // Already included in base class
23+
*
24+
* public function __construct() {
25+
* $this->imetric_dto_version = '2.1.0'; // Override schema version if needed
26+
* }
27+
* }
28+
*
29+
* $integration = new MyIntegration();
30+
* $dto = IMetricService::getDTO($integration);
31+
* $integration->setIMetricDTO($dto);
32+
* // Now metrics can be collected via IMetricService
33+
* </code>
34+
*
35+
* @see IntegrationBase
36+
* @see IntegrationByClassBase
37+
* @see IMetricService
38+
*/
39+
trait IMetricDTOTrait
40+
{
41+
/**
42+
* Stores the metrics DTO instance for this integration.
43+
* Access via getIMetricDTO() method.
44+
* Should not be accessed directly - use getter/setter methods instead.
45+
*
46+
* @var IMetricDTO|null
47+
*/
48+
protected $imetric_dto = null;
49+
50+
/**
51+
* Custom schema version for the metrics DTO.
52+
* If set before calling setIMetricDTO(), this value will override the default DTO version.
53+
* Useful for versioning different integration metrics implementations.
54+
*
55+
* Default: null (uses IMetricDTO default version)
56+
*
57+
* Example:
58+
* <code>
59+
* $integration->imetric_dto_version = '2.5.0';
60+
* IMetricService::getDTO($integration); // Will set dto_version to '2.5.0'
61+
* </code>
62+
*
63+
* @var string|null
64+
*/
65+
public $imetric_dto_version = null;
66+
67+
/**
68+
* Stores the provided IMetricDTO instance and applies version override if set.
69+
*
70+
* This method is called by IMetricService or integration setup code to assign
71+
* a metrics DTO to this integration. If $imetric_dto_version is set on the integration,
72+
* it will override the DTO's default version.
73+
*
74+
* Usage:
75+
* <code>
76+
* $dto = new IMetricDTO();
77+
* $dto->integration_name = 'WooCommerce';
78+
* $integration->setIMetricDTO($dto);
79+
* // Now $integration->getIMetricDTO() returns the same DTO
80+
* </code>
81+
*
82+
* @param IMetricDTO $imetric_dto The metrics DTO instance to store
83+
*
84+
* @return void
85+
*/
86+
public function setIMetricDTO(IMetricDTO $imetric_dto): void
87+
{
88+
$this->imetric_dto = $imetric_dto;
89+
// Apply version override if the integration specifies a custom version
90+
if (isset($this->imetric_dto_version)) {
91+
$this->imetric_dto->dto_version = $this->imetric_dto_version;
92+
}
93+
}
94+
95+
/**
96+
* Retrieves the stored IMetricDTO instance.
97+
*
98+
* Returns the metrics DTO that was previously set via setIMetricDTO(),
99+
* or null if no DTO has been assigned to this integration.
100+
*
101+
* Usage:
102+
* <code>
103+
* $dto = $integration->getIMetricDTO();
104+
* if ($dto) {
105+
* IMetricService::seek($integration, 'operation_name');
106+
* // ... perform operation ...
107+
* IMetricService::lease($integration, 'operation_name');
108+
* }
109+
* </code>
110+
*
111+
* If the constant APBCT_SERVICE__DISABLE_INTEGRATION_METRICS is defined and true,
112+
* this method will return null regardless of the stored DTO.
113+
*
114+
* @return IMetricDTO|null The stored metrics DTO, or null if not set
115+
*/
116+
public function getIMetricDTO()
117+
{
118+
if ($this->imetricIsDisabled()) {
119+
return null;
120+
}
121+
return $this->imetric_dto;
122+
}
123+
124+
public function imetricIsDisabled(): bool
125+
{
126+
return Constant::is(Constant::APBCT_SERVICE__DISABLE_INTEGRATION_METRICS);
127+
}
128+
}

0 commit comments

Comments
 (0)