updated comments

x-pack/plugins/security_solution/server/lib/telemetry/endpoint.mocks.ts

@@ -15,11 +15,20 @@ import { ENDPOINT_PACKAGE_CONSTANT } from './fleet_saved_objects';
 const testAgentId = 'testAgentId';
 const testConfigId = 'testConfigId';
 
+/** Mock OS Platform for endpoint telemetry */
 export const MockOSPlatform = 'somePlatform';
+/** Mock OS Name for endpoint telemetry */
 export const MockOSName = 'somePlatformName';
+/** Mock OS Version for endpoint telemetry */
 export const MockOSVersion = '1';
+/** Mock OS Full Name for endpoint telemetry */
 export const MockOSFullName = 'somePlatformFullName';
 
+/**
+ *
+ * @param lastCheckIn - the last time the agent checked in. Defaults to current ISO time.
+ * @description We request the install and OS related telemetry information from the 'fleet-agents' saved objects in ingest_manager. This mocks that response
+ */
 export const mockFleetObjectsResponse = (
  lastCheckIn = new Date().toISOString()
 ): SavedObjectsFindResponse<Agent> => ({
@@ -36,7 +45,7 @@ export const mockFleetObjectsResponse = (
  config_id: 'randoConfigId',
  type: 'PERMANENT',
  user_provided_metadata: {},
- enrolled_at: '2020-07-08T20:07:44.083Z',
+ enrolled_at: lastCheckIn,
  current_error_events: [],
  local_metadata: {
  elastic: {
@@ -60,13 +69,19 @@ export const mockFleetObjectsResponse = (
  last_checkin: lastCheckIn,
  },
  references: [],
- updated_at: '2020-07-08T20:55:09.216Z',
+ updated_at: lastCheckIn,
  version: 'WzI4MSwxXQ==',
  score: 0,
  },
  ],
 });
 
+/**
+ *
+ * @param running - allows us to set whether the mocked endpoint is in an active or disabled/failed state
+ * @param updatedDate - the last time the endpoint was updated. Defaults to current ISO time.
+ * @description We request the events triggered by the agent and get the most recent endpoint event to confirm it is still running. This allows us to mock both scenarios
+ */
 export const mockFleetEventsObjectsResponse = (
  running?: boolean,
  updatedDate = new Date().toISOString()

x-pack/plugins/security_solution/server/lib/telemetry/endpoint.ts

@@ -47,12 +47,21 @@ export interface AgentLocalMetadata extends AgentMetadata {
  };
 }
 
+/**
+ * @description returns an empty telemetry object to be incrmented and updated within the `getEndpointTelemetryFromFleet` fn
+ */
 export const getDefaultEndpointTelemetry = (): AgentMetadataTelemetry => ({
  total_installed: 0,
  active_within_last_24_hours: 0,
  os: [],
 });
 
+/**
+ * @description This aggregates the telemetry details from the two fleet savedObject sources, `fleet-agents` and `fleet-agent-events` to populate
+ * the telemetry details for endpoint. Since we cannot access our own indices due to `kibana_system` not having access, this is the best alternative.
+ * Once the data is requested, we iterate over all agents with endpoints registered, and then request the events for each active agent (within last 24 hours)
+ * to confirm whether or not the endpoint is still active
+ */
 export const getEndpointTelemetryFromFleet = async (
  savedObjectsClient: ISavedObjectsRepository
 ) => {
@@ -76,6 +85,7 @@ export const getEndpointTelemetryFromFleet = async (
  const endpointMetadataTelemetry = endpointAgents.reduce(
  (metadataTelemetry, { attributes: metadataAttributes }) => {
  const { last_checkin: lastCheckin, local_metadata: localMetadata } = metadataAttributes;
+ // The extended AgentMetadata is just an empty blob, so cast to account for our use case
  const { host, os, elastic } = localMetadata as AgentLocalMetadata;
 
  if (lastCheckin && new Date(lastCheckin) > aDayAgo) {