[doc] Document server-generated metrics

[axw]

Ideally we would have a complete specification for valid documents (#4410). Until we get there, we should at least make sure the Elasticsearch docs we produce are documented -- possibly as part of user-facing elastic.co docs, possibly just as developer-focused docs in the git repo.

For example, these docs should describe the fields present in:

• "transaction" metrics (

  apm-server/x-pack/apm-server/aggregation/txmetrics/aggregator.go

  Lines 358 to 401 in bb856fc

  	func makeMetricset(key transactionAggregationKey, hash uint64, ts time.Time, counts []int64, values []float64) model.Metricset {
  	out := model.Metricset{
  	Timestamp: ts,
  	Name: metricsetName,
  	Metadata: model.Metadata{
  	Service: model.Service{
  	Name: key.serviceName,
  	Version: key.serviceVersion,
  	Environment: key.serviceEnvironment,
  	Agent: model.Agent{Name: key.agentName},
  	},
  	System: model.System{
  	DetectedHostname: key.hostname,
  	Container: model.Container{ID: key.containerID},
  	Kubernetes: model.Kubernetes{PodName: key.kubernetesPodName},
  	},
  	},
  	Event: model.MetricsetEventCategorization{
  	Outcome: key.transactionOutcome,
  	},
  	Transaction: model.MetricsetTransaction{
  	Name: key.transactionName,
  	Type: key.transactionType,
  	Result: key.transactionResult,
  	Root: key.traceRoot,
  	},
  	Samples: []model.Sample{{
  	Name: "transaction.duration.histogram",
  	Counts: counts,
  	Values: values,
  	}},
  	}
  	// Record an timeseries instance ID, which should be uniquely identify the aggregation key.
  	var timeseriesInstanceID strings.Builder
  	timeseriesInstanceID.WriteString(key.serviceName)
  	timeseriesInstanceID.WriteRune(':')
  	timeseriesInstanceID.WriteString(key.transactionName)
  	timeseriesInstanceID.WriteRune(':')
  	timeseriesInstanceID.WriteString(fmt.Sprintf("%x", hash))
  	out.TimeseriesInstanceID = timeseriesInstanceID.String()
  	return out
  	}

  )
• "service_destination" metrics (

  apm-server/x-pack/apm-server/aggregation/spanmetrics/aggregator.go

  Lines 257 to 297 in bb856fc

  	func makeMetricset(timestamp time.Time, key aggregationKey, metrics spanMetrics, interval int64) model.Metricset {
  	out := model.Metricset{
  	Timestamp: timestamp,
  	Name: metricsetName,
  	Metadata: model.Metadata{
  	Service: model.Service{
  	Name: key.serviceName,
  	Environment: key.serviceEnvironment,
  	Agent: model.Agent{Name: key.agentName},
  	},
  	},
  	Event: model.MetricsetEventCategorization{
  	Outcome: key.outcome,
  	},
  	Span: model.MetricsetSpan{
  	DestinationService: model.DestinationService{Resource: key.resource},
  	},
  	Samples: []model.Sample{
  	{
  	Name: "span.destination.service.response_time.count",
  	Value: math.Round(metrics.count),
  	},
  	{
  	Name: "span.destination.service.response_time.sum.us",
  	Value: math.Round(metrics.sum),
  	},
  	},
  	}
  	if interval > 0 {
  	// Only set metricset.period for a positive interval.
  	//
  	// An interval of zero means the metricset is computed
  	// from an instantaneous value, meaning there is no
  	// aggregation period.
  	out.Samples = append(out.Samples, model.Sample{
  	Name: "metricset.period",
  	Value: float64(interval),
  	})
  	}
  	return out
  	}

  )

[axw]

@sqren FYI