Nutzungsdaten in con terra Anwendungen

Übersicht

service.monitor kann in andere con terra Produkte integriert werden, um Daten über deren Nutzungsweise zu sammeln. Die folgende Tabelle zeigt, welche Nutzungsdaten in den Produkten erfasst werden können:

Erfasste Nutzungsdaten Ort der Datenerfassung Unterstützt von

- Grundlegende HTTP-Anfrageparameter (URL, Protokoll)

- Grundlegende HTTP-Antwortparameter (Dauer der Anfrage, HTTP-Status-Code)

- Verwendeter Webbrowser

- Authentifizierungsinformationen (z.B. Benutzername)

- IP-Adresse des Benutzers

(Weitere Informationen unter Beispieldaten)

Serverseitig durch Konfiguration von Servlet-Filtern

security.manager, map.apps

Nutzerinteraktionen (beispielsweise das Aktivieren von Tools, siehe map.apps-Nutzerinteraktionen in Dashboards)

Clientseitig durch JavaScript-Bundles in map.apps, die mit der Usage-Log-REST-Schnittstelle von service.monitor kommunizieren

map.apps

In diesem Kapitel wird die Integration von service.monitor in map.apps und security.manager Enterprise Edition beschrieben. Um die Nutzungsdaten in anderen con terra Produkten zu überwachen, fragen Sie nach Support Plus oder Dienstleistungen für zusätzliche Unterstützung. Viele con terra Produkte unterstützen grundsätzlich die hier dargestellten Integrationswege.

Allgemeiner Ablauf der Integration von service.monitor

  1. Konfiguration der Ingest-Pipeline ct-monitor-analytics für Elasticsearch. Alternative (in Zukunft nicht mehr unterstützt): Pipeline ct-analytics für Logstash

  2. Serverseitige Konfiguration von map.apps und security.manager Enterprise Edition

  3. Neustart des Servlet-Containers

  4. Installation der Kibana Dashboards

  5. Nur für map.apps: Hochladen der Analytics-Bundles in den map.apps Manager und Konfiguration der map.apps-Apps

  6. Kontrolle der Kibana Dashboards, ob Nutzungsdaten erfasst werden

Integration in security.manager Enterprise Edition

Das folgende Bild zeigt eine schematische Darstellung der Integration von service.monitor in security.manager EE.

sec.man usage

Derzeit existieren zwei Wege, auf denen Daten von security.manager weiterverarbeitet und in einen Elasticsearch-Index geschrieben werden können:

  1. Bei der älteren und in Zukunft nicht mehr unterstützten Variante schickt die in security.manager EE integrierte Komponente von service.monitor die erfassten Daten an einen Logstash-Dienst (Logstash ist eine eigenständige Server-Komponente). In Logstash ist eine Pipeline konfiguriert, die die Daten weiterverarbeitet (z.B. eine Anonymisierung von Nutzungsdaten vornimmt) und anschließend an Elasticsearch weiterleitet, wo die Daten in einen Index geschrieben werden (oberer Pfeil). Nachteil dieser Variante ist, dass Logstash als zusätzliche Komponente betrieben werden muss. Dies hat eine höhere Komplexität, einen höheren Ressourcenverbrauch, eine geringere Performance und geringere Zuverlässigkeit zur Folge.

  2. Bei der aktuellen Variante schickt die in security.manager EE integrierte Komponente von service.monitor die erfassten Daten direkt an die Ingest-Schnittstelle von Elasticsearch (unterer Pfeil). Die Pipeline ist innerhalb von Elasticsearch konfiguriert und es ist keine weitere Komponente erforderlich. Die Daten werden in der Pipeline weiterverarbeitet und können ohne weiteren Netzwerkzugriff in einen Elasticsearch-Index geschrieben werden.

Die hier beschriebene Integration ist für security.manager Versionen ab 4.19 gültig. Die Integration für die Versionen 4.15 - 4.18 können Sie in der service.monitor Dokumentation bis Version 4.9.1 nachlesen.
Transportprotokoll zur Pipeline in Abhängigkeit von der service.monitor-Version
service.monitor-Version Transportprotokoll und Pipeline

bis 4.9.1

GELF via UDP (TCP) zur Logstash-Pipeline ct-analytics

ab 4.10.0

HTTP zur Ingest-Pipeline ct-monitor-analytics

(GELF via UDP (TCP) ist abgekündigt, aber weiterhin möglich)

Installations- und Konfigurationsschritte für die WSS-Webapp

Seit security.manager 4.19 ist die service.monitor-Integration Bestandteil von security.manager (WSS-Webapp) und muss lediglich in der application.properties-Datei aktiviert bzw. konfiguriert werden.

Je nachdem ob Sie die Ingest-Pipeline oder die Logstash-Pipeline für das Schreiben der Daten in den Elasticsearch-Index verwenden, fügen Sie die folgenden Konfigurationsparameter in der Datei [SECURITY_MANAGER_DATA_FOLDER]/application.properties hinzu und passen Sie die Werte an Ihre Umgebung an.

Der Servlet-Container muss nach erfolgter Änderung neu gestartet werden.

Ingest-Pipeline (empfohlen)

analytics.enabled=true
analytics.messengerType=elastic
analytics.elastic.url=https://elasticsearch.example.com
analytics.elastic.username=elastic
analytics.elastic.password=changeme
properties

Wenn analytics.messengerType auf elastic gesetzt ist, werden erfasste Nutzungsdaten im Servlet-Filter erkannt.

Zur Funktionsweise: Der mit der Eigenschaft analytics.messengerType aktivierte ElasticsearchMessenger schickt die Daten standardmäßig an den Index analytics-usagelog-tool der Elasticsearch-Instanz (analytics.elastic.url). Dabei wird die Ingest-Pipeline ct-monitor-analytics aktiviert. Diese kann den korrekten Elasticsearch-Index abhängig von den erfassten Daten auswählen und so Daten von anderen con-terra-Produkten (z.B. map.apps-Karteninteraktionen) in einen anderen Index schreiben (z.B. analytics-usagelog-map).

Logstash-Pipeline (abgekündigt)

analytics.enabled=true
analytics.messengerType=gelf
analytics.gelf.host=logstash-host.example.com
analytics.gelf.port=12201
analytics.gelf.protocol=udp
analytics.gelf.identifier=security.manager
properties

Installations- und Konfigurationsschritte für die administration-Webapp

Die Installation der administration-Webapp erfolgt analog zur WSS-Webapp. Zusätzlich müssen die folgenden Schritte durchgeführt werden:

  1. Kopieren Sie die folgenden Dateien vom Verzeichnis [security.manager]/webapps/wss/WEB-INF/lib in das Verzeichnis [security.manager]/webapps/administration/WEB-INF/lib

    • ct-monitor-analytics-message-extender-<version>.jar

    • gelfclient-<version>.jar (nur notwendig für die Logstash Pipeline)

    • netty-*-<version>.Final.jar

  2. Passen Sie die Datei [security.manager]/webapps/administration/WEB-INF/classes/spring-filter-config.xml wie folgt an:

    1. Fügen Sie die Bean-Referenz <ref bean="monitorAnalyticsFilter"/> hinter <ref bean="webSecurityFilter"/> ein (etwa Zeile 50)

    2. Fügen Sie einen der folgenden Abschnitte vor dem schließenden </beans>-Element am Ende der Datei ein.

      Falls Sie die Ingest-Pipeline verwenden:

      <bean id="monitorAnalyticsFilter" factory-bean="monitorAnalyticsFilterFactory" factory-method="create"/>
<bean id="monitorAnalyticsFilterFactory" class="de.conterra.usagelog.support.SecmanEEMonitorFilterFactory" destroy-method="close"
	  p:enabled="${analytics.enabled}"
	  p:messengerType="${analytics.messengerType}"
	  p:elasticServerUrl="${analytics.elastic.url}"
	  p:elasticUserName="${analytics.elastic.username}"
	  p:elasticPassword="${analytics.elastic.password}"
/>
      xml

      Falls Sie die abgekündigte Logstash-Pipeline verwenden:

      <bean id="monitorAnalyticsFilter" factory-bean="monitorAnalyticsFilterFactory" factory-method="create"/>
<bean id="monitorAnalyticsFilterFactory" class="de.conterra.usagelog.support.SecmanEEMonitorFilterFactory" destroy-method="close"
	  p:enabled="${analytics.enabled}"
	  p:messengerType="${analytics.messengerType}"
	  p:identifier="${analytics.gelf.identifier}"
	  p:gelfHost="${analytics.gelf.host}"
	  p:gelfPort="${analytics.gelf.port}"
	  p:gelfProtocol="${analytics.gelf.protocol}"
/>
      xml

Der Servlet-Container muss nach erfolgter Änderung neu gestartet werden.

Integration in map.apps

map.apps usage
INFO

Für die hier beschriebene Integration ist mindestens die map.apps-Version 4.18 erforderlich. Das Vorgehen für die Integration älterer map.apps-Versionen können Sie in der älteren service.monitor-Dokumentation (bis service.monitor-Version 4.9.1) nachlesen.

Installations- und Konfigurationsschritte ab map.apps Version 4.18

Seit map.apps 4.18 ist die service.monitor-Integration Bestandteil von map.apps und muss lediglich über die application.properties aktiviert/konfiguriert werden.

Je nachdem, ob Sie die Ingest-Pipeline oder die Logstash-Pipeline für das Schreiben von Daten in den Elasticsearch-Index verwenden, tragen Sie die folgenden Verbindungsparameter in der Datei [MAPAPPS_DATA_FOLDER]/application.properties ein und passen Sie die Werte an.

Starten Sie anschließend den Servlet-Container (z.B. Tomcat) neu.

Verwendung der Ingest-Pipeline (empfohlen)

Die Ingest-Pipeline wird analog zu der Ingest-Pipeline-Konfiguration im security.manager EE konfiguriert. Wenn analytics.messengerType auf elastic gesetzt ist, werden erfasste Nutzerinteraktionen von map.apps an den Usagelog-REST-Endpunkt geschickt.

Verwendung der Logstash-Pipeline (abgekündigt)

analytics.enabled=true
analytics.messengerType=gelf
analytics.gelf.host=logstash-host.example.com
analytics.gelf.port=12201
analytics.gelf.protocol=udp
analytics.gelf.identifier=map.apps
properties

Analytics-Bundles hochladen

Um die von service.monitor bereitgestellten Bundles zur Erfassung von Nutzerinteraktionen in map.apps zu nutzen, installieren Sie diese im map.apps Manager.

  1. Loggen Sie sich als Benutzer Admin im map.apps Manager ein.

  2. Wechseln Sie zum Bundles Tab.

  3. Klicken Sie + Erstellen und wählen Sie die Datei ct-monitor-analytics-js-[VERSION].jar aus.

Konfiguration von map.apps zur Erfassung von Nutzerinteraktionen in Apps

Neben dem Upload der Bundles müssen Sie die unten aufgeführten Eigenschaften in der application.properties von map.apps hinzufügen oder ändern. Starten Sie anschließend den Servlet-Container neu.

Der Wert der Property data.directory.location unterscheidet sich von der entsprechenden Property in service.monitor.
application.properties (map.apps)
#### service.monitor Integration
analytics.service.url=/monitor-analytics/resources/usage/log
analytics.message.src=map.apps
appservice.default.bundles=analytics_restservice

servicemonitor.base.url=/monitor
analytics.management.role=maAdmin
properties
analytics.service.url

HTTP-Endpunkt zum Erfassen von Nutzungsdaten durch die service.monitor UsageLog-Webapp.

Eigenschaftsstatus: neu
Standardwert: https://analytics-host.example.com/monitor-analytics/resources/usage/log

analytics.message.src

Name der Nachrichtenquelle (für spätere Analysen).

Eigenschaftsstatus: neu
Standardwert: map.apps

appservice.default.bundles

Bundles, die für jede angelegte App geladen werden.

Wenn Sie die Eigenschaft um das analytics_restservice Bundle ergänzen, senden alle Apps standardmäßig die erfassten Daten an die REST-Schnittstelle, die in analytics.service.url konfiguriert wurde. Dies geschieht auch dann, wenn das analytics_restservice Bundle nicht im allowedBundles-Bereich der App enthalten ist und vereinfacht so die Aktivierung von service.monitor für alle Apps.

Wenn Sie eine App über die Live-Konfiguration in map.apps bearbeiten und speichern, werden die hier aufgeführten Bundles zur app.json hinzugefügt. Diese Änderung bleibt auch dann erhalten, wenn Bundles wieder aus der appservice.default.bundles Liste entfernt werden.

Diese Eigenschaft wird nur für Apps angewendet, die in der map.apps Datenbank gespeichert sind und nicht für Apps, die lediglich im Dateisystem liegen.

Eigenschaftsstatus: warning Diese Eigenschaft liegt möglicherweise schon in der application.properties-Datei vor
Standardwert: analytics_restservice (seit map.apps 4.16)

Standardwert: system,templatelayout,analytics_restservice

servicemonitor.base.url

HTTP-Endpunkt zum Aufruf der /monitor-Webapp innerhalb des map.apps Managements.

Eigenschaftsstatus: neu
Standardwert: https://monitoring-host.example.com/monitor

analytics.management.role

Name einer Rolle die für die Anzeige der /monitor Webapp im map.apps Manager nötig ist.

Eigenschaftsstatus: neu
Standardwert: maAdmin

Sollten map.apps und service.monitor nicht auf einem gemeinsamen Host betrieben werden, fügen Sie den entsprechenden Host den allowedProxyUrls in der map.apps application.properties-Datei hinzu.

Aktivierung des Loggings pro App

Um die Protokollierung für eine einzelne App zu aktivieren, fügen Sie ein Bundle mit der Komponente writer (z.B. analytics_restservice) zum Abschnitt allowedBundles in der app.json hinzu. Nutzen Sie appservice.default.bundles, um stattdessen die Protokollierung für alle Anwendungen zu aktivieren.

app.json
{
  "load": {
    "allowedBundles": [
      ...
      "analytics_restservice"
    ]
  }
  ...
}
json

Serverseitig erfasste Nutzungsdaten

Die folgenden Daten werden sowohl in map.apps als auch in security.manager serverseitig erfasst:

useragent

Informationen über Browser und Betriebssystem.

Beispiel:

"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:41.0) Gecko/20100101 Firefox/41.0"
json
client_ip

Anonymisierte Client-IP-Adresse.

Beispiel:

"client_ip": "123.12.12.000"
json
request

Informationen zu Anfrageparametern.

Beispiel:

"request" : {
  "server_host": "secman-host.example.com",
  "url_query": "?queryProperty=testvalue",
  "server_context: "/wss",
  "referrer": "http://www.example.com",
  "protocol": "https"
}
json
auth

Authentifizierungsinformationen wie Benutzername, Benutzerrollen usw.

Beispiel:

"auth": {
  "authenticated": true,
  "user_id": "userA",
  "login_time": "2011-17-10 11:17:50",
  "group_name": "sampleGroup",
  "roles": [
    "admin",
    "editor"
  ]
}
json
response

Informationen zu Antwortparametern.

Beispiel:

"response": {
  "status": 200
}
json
response_time

Antwortzeit in Nanosekunden und Antwortzeit in Millisekunden.

Beispiel:

"response_time": 12345678,
"response_time_ms": 1234.5678
json