diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 81034b076..234b10154 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -22,6 +22,7 @@ Generic Start * Manage instances ** xref:managing-instances/instance-actions.adoc[Instance actions] ** xref:managing-instances/instance-details.adoc[Instance details] +** xref:managing-instances/self-managed.adoc[Self-managed instances] ** xref:managing-instances/secondaries.adoc[Secondaries] ** xref:managing-instances/instance-resources.adoc[Resources] ** xref:managing-instances/custom-endpoints.adoc[Custom endpoints] @@ -113,6 +114,15 @@ Generic Start * xref:billing.adoc[Billing] +* Fleet management +** xref:fleet-management/overview.adoc[Overview] +** xref:fleet-management/setup.adoc[Add a deployment] +** xref:fleet-management/inspect-deployment.adoc[Inspect deployment] +** xref:fleet-management/deployment-details.adoc[Deployment details] +** xref:fleet-management/graph-view.adoc[Graph view] +** xref:fleet-management/procedures.adoc[Plugin procedures] +** xref:fleet-management/data.adoc[Data transparency] + * Connecting applications ** xref:connecting-applications/overview.adoc[Drivers and libraries] ** xref:connecting-applications/query-api.adoc[Using Query API] diff --git a/modules/ROOT/images/add-sm-deployment.png b/modules/ROOT/images/add-sm-deployment.png new file mode 100644 index 000000000..3ec7ed2e3 Binary files /dev/null and b/modules/ROOT/images/add-sm-deployment.png differ diff --git a/modules/ROOT/images/deployment-graph.png b/modules/ROOT/images/deployment-graph.png new file mode 100644 index 000000000..5f2a606ea Binary files /dev/null and b/modules/ROOT/images/deployment-graph.png differ diff --git a/modules/ROOT/images/sm-instances-header.png b/modules/ROOT/images/sm-instances-header.png new file mode 100644 index 000000000..96642f516 Binary files /dev/null and b/modules/ROOT/images/sm-instances-header.png differ diff --git a/modules/ROOT/pages/fleet-management/data.adoc b/modules/ROOT/pages/fleet-management/data.adoc new file mode 100644 index 000000000..1180282bb --- /dev/null +++ b/modules/ROOT/pages/fleet-management/data.adoc @@ -0,0 +1,322 @@ += Data transparency + +This document describes the data structures used in fleet management messages. + +== ConnectMessage + +Message sent from the server to the Fleet Management service to establish a connection + +[cols="1,1,1"] +|=== +|Field |Type |Description +|server_id +|String +|Unique identifier for the server +|name +|String +|Name of the server +|dbms_id +|String +|Unique identifier for the DBMS instance +|server_version +|String +|Version of the server +|project_id +|String +|Identifier for the project +|plugin_version +|String +|Version of the plugin +|build_profile +|String +|Build profile of the plugin +|=== + +== MetricsMessage + +Message sent from the server to the Fleet Management service containing metrics data + +[cols="1,1,1"] +|=== +|Field |Type |Description +|timestamp +|long +|Unix timestamp in milliseconds when the message was created +|project_id +|String +|Identifier for the project +|dbms_id +|String +|Unique identifier for the DBMS instance +|server_id +|String +|Unique identifier for the server +|metrics +|Map> +|Map of metric names to lists of DataPoint objects. Values are dynamically populated from the Fleet Management server. +|metrics<>[].tags +|Map +|Map of string key-value pairs providing additional context for the metric +|metrics<>[].value +|Double +|Double value representing the metric measurement +|=== + +== Neo4jConfigMessage + +Message sent from the server to the Fleet Management service containing neo4j config data + +[cols="1,1,1"] +|=== +|Field |Type |Description +|timestamp +|long +|Unix timestamp in milliseconds when the message was created +|project_id +|String +|Identifier for the project +|dbms_id +|String +|Unique identifier for the DBMS instance +|server_id +|String +|Unique identifier for the server +|neo4j_config +|Map +|Map of neo4j config names to config values. Values are dynamically populated from the Fleet Management server. +|=== + +== PingMessage + +Message sent from the server to the Fleet Management service to retrieve configuration updates + +[cols="1,1,1"] +|=== +|Field |Type |Description +|server_id +|String +|Unique identifier for the server +|server_version +|String +|Version of the server +|project_id +|String +|Identifier for the project +|=== + +== ReportingMessage + +Message sent from the server to the Fleet Management service containing reporting data + +[cols="1,1,1"] +|=== +|Field |Type |Description +|timestamp +|long +|Unix timestamp in milliseconds when the message was created +|projectId +|String +|Identifier for the project +|dbms +|Dbms +|DBMS information object +|dbms.dbmsId +|String +|Unique identifier for the DBMS instance +|dbms.serverId +|String +|Unique identifier for the server +|dbms.databases +|List +|List of database names +|dbms.edition +|String +|Edition of the DBMS (e.g., Enterprise, Community) +|dbms.packaging +|String +|Packaging of DBMS installation +|dbms.servers +|List +|List of servers in the DBMS cluster +|dbms.servers[].serverId +|String +|Unique identifier for the server +|dbms.servers[].name +|String +|Name of the server +|dbms.servers[].address +|String +|Network address of the server +|dbms.servers[].health +|String +|Current health status of the server +|dbms.servers[].state +|String +|Current state of the server +|dbms.servers[].modeConstraint +|String +|Mode constraint of the server +|dbms.servers[].version +|String +|Neo4j version of the server +|dbms.servers[].databases +|List +|List of databases hosted on this server +|dbms.servers[].databases[].name +|String +|Name of the database +|dbms.servers[].databases[].role +|String +|Role of the database in the cluster +|dbms.servers[].databases[].type +|String +|Type of the database in the cluster +|dbms.servers[].databases[].aliases +|List +|List of database aliases +|dbms.servers[].databases[].access +|String +|Access level of the database +|dbms.servers[].databases[].databaseId +|String +|Unique identifier for the database +|dbms.servers[].databases[].requestedStatus +|String +|Requested status of the database +|dbms.servers[].databases[].currentStatus +|String +|Current status of the database +|dbms.servers[].databases[].statusMessage +|String +|Status message describing the current state +|dbms.servers[].databases[].default +|boolean +|Whether this is the default database +|dbms.servers[].databases[].home +|boolean +|Whether this is the home database +|dbms.servers[].databases[].currentPrimariesCount +|Integer +|Current number of primaries for this database +|dbms.servers[].databases[].currentSecondariesCount +|Integer +|Current number of secondaries for this database +|dbms.servers[].databases[].requestedPrimariesCount +|Integer +|Requested number of primaries for this database +|dbms.servers[].databases[].requestedSecondariesCount +|Integer +|Requested number of secondaries for this database +|dbms.servers[].databases[].creationTime +|long +|Timestamp when the database was created +|dbms.servers[].databases[].lastStartTime +|long +|Timestamp when the database was last started +|dbms.servers[].databases[].store +|String +|Store format of the database +|dbms.servers[].databases[].writer +|boolean +|Whether this instance is a writer for this database +|dbms.servers[].databases[].lastCommittedTxn +|Integer +|Last committed transaction ID +|dbms.servers[].databases[].replicationLag +|Integer +|Current replication lag +|dbms.servers[].databases[].graphCount +|GraphCount +|Current graph counts for the database +|dbms.servers[].databases[].graphCount.node_count +|Long +|Number of nodes in the graph +|dbms.servers[].databases[].graphCount.relationship_count +|Long +|Number of relationships in the graph +|dbms.servers[].databases[].graphShards +|List +|List of graph shards of this database +|dbms.servers[].databases[].propertyShards +|List +|List of property shards of this database +|dbms.servers[].license +|License +|Main license information +|dbms.servers[].license.type +|String +|Type of the license +|dbms.servers[].license.state +|String +|Current state of the license +|dbms.servers[].license.daysLeftOnTrial +|Integer +|Number of days remaining in trial period +|dbms.servers[].license.totalTrialDays +|Integer +|Total number of days in trial period +|dbms.servers[].bloomLicense +|License +|Bloom license information +|dbms.servers[].bloomLicense.type +|String +|Type of the license +|dbms.servers[].bloomLicense.state +|String +|Current state of the license +|dbms.servers[].bloomLicense.daysLeftOnTrial +|Integer +|Number of days remaining in trial period +|dbms.servers[].bloomLicense.totalTrialDays +|Integer +|Total number of days in trial period +|dbms.servers[].gdsLicense +|License +|GDS license information +|dbms.servers[].gdsLicense.type +|String +|Type of the license +|dbms.servers[].gdsLicense.state +|String +|Current state of the license +|dbms.servers[].gdsLicense.daysLeftOnTrial +|Integer +|Number of days remaining in trial period +|dbms.servers[].gdsLicense.totalTrialDays +|Integer +|Total number of days in trial period +|dbms.servers[].plugins +|List +|List of plugins installed on the server +|dbms.servers[].plugins[].filename +|String +|Filename of the plugin +|dbms.servers[].plugins[].name +|String +|Manifest name of the plugin, if available +|dbms.servers[].plugins[].version +|String +|Manifest version of the plugin, if available +|dbms.servers[].plugins[].vendor +|String +|Manifest vendor of the plugin, if available +|pluginVersion +|String +|Version of the fleet management plugin +|osName +|String +|Operating system name +|osVersion +|String +|Operating system version +|osArch +|String +|Operating system architecture +|jvmVersion +|String +|Java Virtual Machine version +|jvmVendor +|String +|Java Virtual Machine vendor +|=== + diff --git a/modules/ROOT/pages/fleet-management/deployment-details.adoc b/modules/ROOT/pages/fleet-management/deployment-details.adoc new file mode 100644 index 000000000..f1fd47b1d --- /dev/null +++ b/modules/ROOT/pages/fleet-management/deployment-details.adoc @@ -0,0 +1,30 @@ +[[sm-deployment-details]] += Deployment details +:description: This page describes deployment details + +From the deployment card or deployment table, select the more menu *(…​)*. +In the graph view, the same menu can be accessed by right-clicking the DBMS node. Then select *Show details* from the menu options. + +On the right side of the header, the view selector allows you to choose between two views: *table* view or *graph* view (see xref:fleet-management/graph-view.adoc[Graph view]). + +== Table view + +The table view shows topology data in a tabular format. Three different tables are selectable using the dropdown in the table header. + +* Servers +* Databases +* Database instances + +=== Servers + +The *Servers* table shows all servers in the deployment. + +For more information, see the link:https://neo4j.com/docs/operations-manual/current/clustering/monitoring/show-servers-monitoring/[documentation] for instructions on how to install plugins. for the `SHOW SERVERS` procedure, which is called by the plugin to obtain the data. + +=== Databases and Database instances + +The *Databases* table shows all databases in the deployment. + +A *Database instance* in this context refers to an instance of a logical database running on a specific server. + +For more information, see the link:https://neo4j.com/docs/operations-manual/current/database-administration/standard-databases/listing-databases/[documentation] for instructions on how to install plugins. for the `SHOW DATABASES` procedure, which is called by the plugin to obtain the data. \ No newline at end of file diff --git a/modules/ROOT/pages/fleet-management/graph-view.adoc b/modules/ROOT/pages/fleet-management/graph-view.adoc new file mode 100644 index 000000000..acabc88fc --- /dev/null +++ b/modules/ROOT/pages/fleet-management/graph-view.adoc @@ -0,0 +1,92 @@ +[[sm-deployment-graph]] += Graph view +:description: This page describes the deployment graph view + +In the graph view, the topology data is displayed as a graph. The graph shows the servers, databases and database instances in the deployment. + +Depending on whether the view is accessed from *Instances* or *Deployment details*, it will show either all deployments or just the selected deployment. + +[.shadow] +image::deployment-graph.png[] + +== Legend + +To the right of the graph, there is a panel that enumerates the node labels and relationship types. +If an entity is selected, the panel displays the properties of that entity. + +The panel can be toggled by clicking the button in the top right corner of the graph view. The *Download* button is located to the left of that button and allows you to download the graph as a PNG image. + +In the bottom right corner of the graph view is a stack of buttons, from top to bottom: + +* *Hierarchy view*—Toggles between force-directed or hierarchical layouts of the graph. + +* *Expand all*—Expands all nodes in the graph, showing all relationships. + +* *Collapse all*—Collapses all nodes in the graph, hiding relationships. + +* *Fit to screen*—Fits the graph to the screen, adjusting the zoom level and centering the graph. + +== Nodes + +The following node labels are used in the graph view. + +[cols="1,2"] +|=== +|Label |Description + +|DBMS +|Represents a Neo4j cluster + +|Server +|A server belonging to a Neo4j cluster + +|Database +|A logical non-system database + +|SystemDatabase +|The special system database, used for internal settings + +|Online +|A label which is used for a DBMS that is online. Nodes with this label are assigned a green color. + +|Offline +|A label which is used for a DBMS that is offline. Nodes with this label are assigned a red color. + +|Degraded +|A label which is used for a DBMS that has a degraded status (for example, some of the servers are offline). Nodes with this label are assigned a yellow color. + +|=== + +== Relationships + +The following relationship types are used in the graph view. + +[cols="1,2"] +|=== +|Relationship type |Description + +|COMPRISES +|Indicates that a DBMS comprises one or more servers + +|HAS_DATABASE +|A DBMS has one or more databases + +|PRIMARY_FOR +|Indicates that a server acts as a primary for a database + +|SECONDARY_FOR +|Indicates that a server acts as a secondary for a database + +|LEADER_FOR +|Used for older Neo4j versions. Indicates that a server acts as a leader for a database + +|FOLLOWER_FOR +|Used for older Neo4j versions. Indicates that a server acts as a follower for a database + +|READ_REPLICA_FOR +|Used for older Neo4j versions. Indicates that a server acts as a read replica for a database + +|STANDALONE_FOR +|Used for older Neo4j versions. Indicates that a server acts as a standalone replica for a database + +|=== \ No newline at end of file diff --git a/modules/ROOT/pages/fleet-management/inspect-deployment.adoc b/modules/ROOT/pages/fleet-management/inspect-deployment.adoc new file mode 100644 index 000000000..e61138a6e --- /dev/null +++ b/modules/ROOT/pages/fleet-management/inspect-deployment.adoc @@ -0,0 +1,75 @@ +[[sm-inspect-deployment]] += Inspect deployment +:description: This page describes inspecting the deployment. + +From the deployment card or deployment table, select the more menu *(…​)*. +In the graph view, the same menu can be accessed by right-clicking the DBMS node. Then select *Inspect* from the menu options. + +== Overview + +Aside from the deployment name and status, the following information is displayed. + +[cols="1,2"] +|=== +|Property |Description + +|Version +|The Neo4j version + +|Edition +|The Neo4j edition + +|Packaging +|The Neo4j packaging used for deploying this cluster + +|Servers +|A list of servers in the cluster + +|Registered by +|Email address of the user who originally registered this deployment + +|=== + +== Token + +This section contains information and actions related to the token used to authenticate the deployment with Aura. + +[cols="1,2"] +|=== +|Property |Description + +|Status +|Whether the token is in use or not + +|Registered by +|Email address of the user who originally registered this deployment + +|Creation time +|The time and date when the token was created + +|Expires on +|The time and date when the token expires + +|Auto-rotated +|Whether the token is configured to be automatically rotated before its expiry + +|=== + +To perform token related actions, select the token menu *(…​)*. + +* *Regenerate*—This will remove the current token and generate a new one. Any plugin using the previous token will be logged out. + +* *Release*—This option will delete the association between this deployment and the current Neo4j cluster. This allows another cluster to claim the deployment. This is especially useful when migrating to a new major Neo4j version. Note that existing topology data will be cleared. + +* *Delete*—Selecting this option will permanently invalidate and delete the token. + +== License + +This section contains information about Neo4j licenses detected on this cluster. +Supported products are: + +* Neo4j +* Graph Data Science +* Bloom + +For each detected product, information displayed includes the *type* of license (free/trial/commercial), the *status* (valid/expired) and the *expiry date* if applicable. \ No newline at end of file diff --git a/modules/ROOT/pages/fleet-management/overview.adoc b/modules/ROOT/pages/fleet-management/overview.adoc new file mode 100644 index 000000000..03d19c49a --- /dev/null +++ b/modules/ROOT/pages/fleet-management/overview.adoc @@ -0,0 +1,28 @@ += Overview + +Get an enterprise-wide view of all your Neo4j systems—Aura-managed or self-managed. + +For enterprise customers operating in hybrid environments, it’s common to have a mix of *Aura-managed* and *self-managed* Neo4j deployments. By integrating self-managed deployments into the Aura Console, organizations can simplify operations, reduce overhead, and plan for full migration when ready. + +== *Centralized management* +Register self-managed Neo4j deployments directly in the Aura Console to: + +* Monitor and manage all Neo4j databases across your organization in one place +* Monitor health and performance metrics +* Run Cypher queries, explore graphs, and view dashboards + +== Features + +Fleet management offers a wealth of features to manage and monitor your self-managed Neo4j deployments: + +* Metrics +* Topology views (graph and tabular format) +* Server configuration viewer +* Database metadata +* License status viewer + +In addition to these features, the following user tools are available for self-managed deployments: + +* Query +* Explore +* Dashboards \ No newline at end of file diff --git a/modules/ROOT/pages/fleet-management/procedures.adoc b/modules/ROOT/pages/fleet-management/procedures.adoc new file mode 100644 index 000000000..6dd94e14c --- /dev/null +++ b/modules/ROOT/pages/fleet-management/procedures.adoc @@ -0,0 +1,33 @@ += Plugin procedures + +The fleet management plugin provides a set of procedures to manage and monitor the connection to Aura. These procedures can be executed in Neo4j Browser or any other Neo4j client. + +[cols="1,3,1,1"] +|=== +|Procedure |Description |Arguments |Return + +|fleetManagement.status +|Check the current status of the plugin and its connectivity to Aura. +|- +|Boolean active, Boolean connected, String statusMessage + +|fleetManagement.registerToken +|Register the deployment with Aura using the provided registration token and start reporting. +|String token +|String + +|fleetManagement.disable +|Disconnect from Aura, remove the existing token and disable the fleet management feature. +|- +|String + +|fleetManagement.reportedData +|Obtain a complete listing of all data the plugin is reporting to Aura. A copy of this data can be found on the xref:fleet-management/data.adoc[Data transparency] page. +|- +|Array of (String messageType, String fieldPath, String description, String fieldType, String values) + +|fleetManagement.debugLogging +|Enable or disable debug and traffic logging +|Boolean debugLogging, Boolean trafficLogging +|String +|=== \ No newline at end of file diff --git a/modules/ROOT/pages/fleet-management/setup.adoc b/modules/ROOT/pages/fleet-management/setup.adoc new file mode 100644 index 000000000..64a25d850 --- /dev/null +++ b/modules/ROOT/pages/fleet-management/setup.adoc @@ -0,0 +1,70 @@ += Add a deployment + +Adding a self-managed deployment to fleet management is easy. +Start by clicking the *Add deployment* button in the *Self-managed* tab under *Instances*. + +[.shadow] +image::add-sm-deployment.png[] + +The wizard provides two top-level options. + +* *Monitor deployment* - this option should be selected if you want to use fleet management. +* *URL connection* - this option allows you to add an unmonitored deployment that can still be connected to using the provided connection URL. + +== Set up the plugin + +The next step of the wizard walks you through the process of adding the fleet management plugin to your Neo4j cluster. + +=== Download the plugin + +Follow the link in the UI to download the plugin. +Neo4j Fleet management plugin has the name format `neo4j-fleet-management-plugin-VERSION-NEO4J_VERSION.jar`. +Choose the appropriate plugin for your Neo4j version. + +=== Install plugin + +The plugin needs to be installed *on each server* of the cluster. See the link:https://neo4j.com/docs/operations-manual/current/configuration/plugins/[Neo4j documentation] for instructions on how to install plugins. + + +To allow the plugin procedures to run, you need to enable them in the configuration. +Add `fleetManagement.*` to `dbms.security.procedures.unrestricted`. +For example: + +===== +[source] +---- +dbms.security.procedures.unrestricted=fleetManagement.* +---- +===== + +If `dbms.security.procedures.allowlist` is set in your configuration, `fleetManagement.*` should also be added to this setting, otherwise no change is needed. + +===== +[source] +---- +dbms.security.procedures.allowlist=,fleetManagement.* +---- +===== + +=== Restart Neo4j + +Once the plugin is installed and configured, restart Neo4j to load the plugin. + +=== Verify the plugin is installed correctly + +By calling the procedure `CALL fleetManagement.status()`, for example in Neo4j Browser, you can verify that the plugin is installed correctly. + +If the procedure returns a result, the plugin is installed, and you can select *Next* in the wizard. + +== Register the deployment + +[WARNING] +==== +Registering a token will associate the cluster to the Aura project which was used to generate the token. *Never register a token obtained from a third party.* +==== + +In the next step of the wizard, choose an expiry time for the generated token and whether to enable automatic rotation. +If auto-rotation is enabled, the plugin will automatically negotiate a new token before the current one is expired. Then select *Next*. + +In the final step, you will see the generated token. Save it in a secure location and then register it using the procedure `fleetManagement.registerToken`. +It only needs to be registered once to take effect across the whole cluster. \ No newline at end of file diff --git a/modules/ROOT/pages/managing-instances/self-managed.adoc b/modules/ROOT/pages/managing-instances/self-managed.adoc new file mode 100644 index 000000000..f054a32bb --- /dev/null +++ b/modules/ROOT/pages/managing-instances/self-managed.adoc @@ -0,0 +1,48 @@ +[[self-managed-instances]] += Self-managed instances +:description: This page describes the self-managed instance overview. + +From the *Self-managed* tab, you can add and monitor your self-managed Neo4j deployments. Even though Neo4j does not host these instances, you can still connect to them from the Aura console. + +This functionality is exhaustively documented in the xref:fleet-management/overview.adoc[Fleet management] section. + +== Overview + +In the *Self-managed* tab under *Instances*, you can see all self-managed Neo4j deployments that have been added to your Aura project. + +See xref:fleet-management/setup.adoc[Add a deployment] for more information on adding your deployments. + +[.shadow] +image::sm-instances-header.png[] + +This view provides several powerful ways to filter and display your deployments. + +The *search bar* allows you to rapidly find what you are looking for by searching by name. + +Next to the search bar is a *filter button*. +Clicking the *filter button* brings up a dialog with the following filters. + +.Filters +[cols="1,1"] +|=== +| Filter | Description + +|Status +|The overall deployment state + +|Version +|The version of Neo4j running on the deployment + +|Edition +|The edition of Neo4j running on the deployment + +|Packaging +|The packaging that was used to deploy Neo4j + +|State +|State is a special category that allows you to quickly find deployments in a few key categories, such as whether a connection URL exists or whether there are problems with the plugin or licenses. +|=== + +=== Views + +On the right side of the header, the view selector allows you to choose between three views: *table* view, *graph* view or *card* view. \ No newline at end of file