Skip to content

Commit

Permalink
DOCSP-29036: Performance monitoring files
Browse files Browse the repository at this point in the history
  • Loading branch information
@norareidy
norareidy committed Mar 25, 2024
1 parent 9acdaf2 commit 06baccd
Show file tree
Hide file tree
Showing 2 changed files with 139 additions and 127 deletions.
186 changes: 93 additions & 93 deletions source/docs-libmongoc/application-performance-monitoring.txt
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. _mongoc_application_performance_monitoring
.. _mongoc_application_performance_monitoring:

========================================
Application Performance Monitoring (APM)
Expand Down Expand Up @@ -32,45 +32,45 @@ This example program prints:

.. code-block:: none

Command drop started on 127.0.0.1:
{ "drop" : "test" }

Command drop succeeded:
{ "ns" : "test.test", "nIndexesWas" : 1, "ok" : 1.0 }

Command insert started on 127.0.0.1:
{
"insert" : "test",
"ordered" : true,
"documents" : [
{ "_id" : 0 }, { "_id" : 1 }
]
}

Command insert succeeded:
{ "n" : 2, "ok" : 1.0 }

Command insert started on 127.0.0.1:
{
"insert" : "test",
"ordered" : true,
"documents" : [
{ "_id" : 0 }
]
}

Command insert succeeded:
{
"n" : 0,
"writeErrors" : [
{ "index" : 0, "code" : 11000, "errmsg" : "duplicate key" }
],
"ok" : 1.0
}

started: 3
succeeded: 3
failed: 0
Command drop started on 127.0.0.1:
{ "drop" : "test" }

Command drop succeeded:
{ "ns" : "test.test", "nIndexesWas" : 1, "ok" : 1.0 }

Command insert started on 127.0.0.1:
{
"insert" : "test",
"ordered" : true,
"documents" : [
{ "_id" : 0 }, { "_id" : 1 }
]
}

Command insert succeeded:
{ "n" : 2, "ok" : 1.0 }

Command insert started on 127.0.0.1:
{
"insert" : "test",
"ordered" : true,
"documents" : [
{ "_id" : 0 }
]
}

Command insert succeeded:
{
"n" : 0,
"writeErrors" : [
{ "index" : 0, "code" : 11000, "errmsg" : "duplicate key" }
],
"ok" : 1.0
}

started: 3
succeeded: 3
failed: 0

The output has been edited and formatted for clarity. Depending on your server configuration, messages may
include metadata like database name, logical session ids, or cluster times that are not shown here.
Expand All @@ -81,71 +81,71 @@ overall command with ``"ok": 1``.
SDAM Monitoring Example
-----------------------

.. literalinclude:: ../examples/example-sdam-monitoring.c
.. literalinclude:: /includes/examples/example-sdam-monitoring.c
:language: c
:caption: example-sdam-monitoring.c

Start a 3-node replica set on localhost with set name "rs" and start the program:

.. code-block:: none

./example-sdam-monitoring "mongodb://localhost:27017,localhost:27018/?replicaSet=rs"
./example-sdam-monitoring "mongodb://localhost:27017,localhost:27018/?replicaSet=rs"

This example program prints something like:

.. code-block:: none

topology opening
topology changed: Unknown -> ReplicaSetNoPrimary
secondary UNAVAILABLE
primary UNAVAILABLE
server opening: localhost:27017
server opening: localhost:27018
localhost:27017 heartbeat started
localhost:27018 heartbeat started
localhost:27017 heartbeat succeeded: { ... reply ... }
server changed: localhost:27017 Unknown -> RSPrimary
server opening: localhost:27019
topology changed: ReplicaSetNoPrimary -> ReplicaSetWithPrimary
new servers:
RSPrimary localhost:27017
secondary UNAVAILABLE
primary AVAILABLE
localhost:27019 heartbeat started
localhost:27018 heartbeat succeeded: { ... reply ... }
server changed: localhost:27018 Unknown -> RSSecondary
topology changed: ReplicaSetWithPrimary -> ReplicaSetWithPrimary
previous servers:
RSPrimary localhost:27017
new servers:
RSPrimary localhost:27017
RSSecondary localhost:27018
secondary AVAILABLE
primary AVAILABLE
localhost:27019 heartbeat succeeded: { ... reply ... }
server changed: localhost:27019 Unknown -> RSSecondary
topology changed: ReplicaSetWithPrimary -> ReplicaSetWithPrimary
previous servers:
RSPrimary localhost:27017
RSSecondary localhost:27018
new servers:
RSPrimary localhost:27017
RSSecondary localhost:27018
RSSecondary localhost:27019
secondary AVAILABLE
primary AVAILABLE
topology closed

Events:
server changed: 3
server opening: 3
server closed: 0
topology changed: 4
topology opening: 1
topology closed: 1
heartbeat started: 3
heartbeat succeeded: 3
heartbeat failed: 0
topology opening
topology changed: Unknown -> ReplicaSetNoPrimary
secondary UNAVAILABLE
primary UNAVAILABLE
server opening: localhost:27017
server opening: localhost:27018
localhost:27017 heartbeat started
localhost:27018 heartbeat started
localhost:27017 heartbeat succeeded: { ... reply ... }
server changed: localhost:27017 Unknown -> RSPrimary
server opening: localhost:27019
topology changed: ReplicaSetNoPrimary -> ReplicaSetWithPrimary
new servers:
RSPrimary localhost:27017
secondary UNAVAILABLE
primary AVAILABLE
localhost:27019 heartbeat started
localhost:27018 heartbeat succeeded: { ... reply ... }
server changed: localhost:27018 Unknown -> RSSecondary
topology changed: ReplicaSetWithPrimary -> ReplicaSetWithPrimary
previous servers:
RSPrimary localhost:27017
new servers:
RSPrimary localhost:27017
RSSecondary localhost:27018
secondary AVAILABLE
primary AVAILABLE
localhost:27019 heartbeat succeeded: { ... reply ... }
server changed: localhost:27019 Unknown -> RSSecondary
topology changed: ReplicaSetWithPrimary -> ReplicaSetWithPrimary
previous servers:
RSPrimary localhost:27017
RSSecondary localhost:27018
new servers:
RSPrimary localhost:27017
RSSecondary localhost:27018
RSSecondary localhost:27019
secondary AVAILABLE
primary AVAILABLE
topology closed

Events:
server changed: 3
server opening: 3
server closed: 0
topology changed: 4
topology opening: 1
topology closed: 1
heartbeat started: 3
heartbeat succeeded: 3
heartbeat failed: 0

The driver connects to the mongods on ports 27017 and 27018, which were specified in the URI, and determines
which is primary. It also discovers the third member, "localhost:27019", and adds it to the topology.
Expand Down
80 changes: 46 additions & 34 deletions source/docs-libmongoc/authentication.txt
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
.. _mongoc_authentication:

==============
Authentication
==============

Expand All @@ -9,26 +10,29 @@ Authentication
:depth: 2
:class: singlecol

This guide covers the use of authentication options with the MongoDB C Driver. Ensure that the MongoDB server is also properly configured for authentication before making a connection. For more information, see the `MongoDB security documentation <https://www.mongodb.com/docs/manual/administration/security/>`_.
This guide covers the use of authentication options with the MongoDB C Driver. Ensure that the MongoDB server
is also properly configured for authentication before making a connection. For more information, see the
`MongoDB security documentation <https://www.mongodb.com/docs/manual/administration/security/>`_.

The MongoDB C driver supports several authentication mechanisms through the use of MongoDB connection URIs.

By default, if a username and password are provided as part of the connection string (and an optional authentication database), they are used to connect via the default authentication mechanism of the server.
By default, if a username and password are provided as part of the connection string (and an optional authentication
database), they are used to connect via the default authentication mechanism of the server.

Check failure on line 20 in source/docs-libmongoc/authentication.txt

View workflow job for this annotation

GitHub Actions / TDBX Vale rules 

[vale] reported by reviewdog 🐶
[MongoDB.AvoidObscure] Use 'through, by' instead of 'via'.

Raw Output:
{"message": "[MongoDB.AvoidObscure] Use 'through, by' instead of 'via'.", "location": {"path": "source/docs-libmongoc/authentication.txt", "range": {"start": {"line": 20, "column": 37}}}, "severity": "ERROR"}

To select a specific authentication mechanism other than the default, see the list of supported mechanism below.

.. code-block:: none

mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");

Currently supported values for the authMechanism connection string option are:

* :ref:`SCRAM-SHA-1 <authentication_scram_sha_1>`
* :ref:`MONGODB-CR (deprecated) <authentication_mongodbcr>`
* :ref:`GSSAPI <authentication_kerberos>`
* :ref:`PLAIN <authentication_plain>`
* :ref:`X509 <authentication_x509>`
* :ref:`MONGODB-AWS <authentication_aws>`
- :ref:`SCRAM-SHA-1 <authentication_scram_sha_1>`
- :ref:`MONGODB-CR (deprecated) <authentication_mongodbcr>`
- :ref:`GSSAPI <authentication_kerberos>`
- :ref:`PLAIN <authentication_plain>`
- :ref:`X509 <authentication_x509>`
- :ref:`MONGODB-AWS <authentication_aws>`

.. _authentication_scram_sha_256:

Expand All @@ -46,37 +50,41 @@ SCRAM-SHA-1 and SCRAM-SHA-256 credentials:

.. code-block:: none

mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
/* the correct authMechanism is negotiated between the driver and server. */
mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");
/* the correct authMechanism is negotiated between the driver and server. */

Alternatively, SCRAM-SHA-256 can be explicitly specified as an authMechanism.

.. code-block:: none

mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-256&authSource=mydb");
mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-256&authSource=mydb");

.. _authentication_scram_sha_1:

Basic Authentication (SCRAM-SHA-1)
----------------------------------

The default authentication mechanism before MongoDB 4.0 is ``SCRAM-SHA-1`` (`RFC 5802 <http://tools.ietf.org/html/rfc5802>`_). Using this authentication mechanism means that the password is never actually sent over the wire when authenticating, but rather a computed proof that the client password is the same as the password the server knows.
The default authentication mechanism before MongoDB 4.0 is ``SCRAM-SHA-1`` (`RFC 5802
<http://tools.ietf.org/html/rfc5802>`_). Using this authentication mechanism means that the password
is never actually sent over the wire when authenticating, but rather a computed proof that the client
password is the same as the password the server knows.

.. code-block:: none

mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-1&authSource=mydb");
mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authMechanism=SCRAM-SHA-1&authSource=mydb");

.. note::

``SCRAM-SHA-1`` authenticates against the ``admin`` database by default. If the user is created in another database, then specifying the authSource is required.
``SCRAM-SHA-1`` authenticates against the ``admin`` database by default. If the user is created in
another database, then specifying the authSource is required.

.. _authentication_mongodbcr:

Legacy Authentication (MONGODB-CR)
----------------------------------

The MONGODB-CR authMechanism is deprecated and will no longer function in MongoDB 4.0. Instead, specify no authMechanism and the driver
will use an authentication mechanism compatible with your server.
The MONGODB-CR authMechanism is deprecated and will no longer function in MongoDB 4.0. Instead, specify
no authMechanism and the driver will use an authentication mechanism compatible with your server.

.. _authentication_kerberos:

Expand All @@ -85,51 +93,55 @@ GSSAPI (Kerberos) Authentication

.. note::

On UNIX-like environments, Kerberos support requires compiling the driver against ``cyrus-sasl``.
On UNIX-like environments, Kerberos support requires compiling the driver against ``cyrus-sasl``.

On Windows, Kerberos support requires compiling the driver against Windows Native SSPI or ``cyrus-sasl``. The default configuration of the driver will use Windows Native SSPI.
On Windows, Kerberos support requires compiling the driver against Windows Native SSPI or ``cyrus-sasl``.
The default configuration of the driver will use Windows Native SSPI.

To modify the default configuration, use the cmake option ``ENABLE_SASL``.
To modify the default configuration, use the cmake option ``ENABLE_SASL``.

``GSSAPI`` (Kerberos) authentication is available in the Enterprise Edition of MongoDB. To authenticate using ``GSSAPI``, the MongoDB C driver must be installed with SASL support.
``GSSAPI`` (Kerberos) authentication is available in the Enterprise Edition of MongoDB. To authenticate
using ``GSSAPI``, the MongoDB C driver must be installed with SASL support.

On UNIX-like environments, run the ``kinit`` command before using the following authentication methods:

.. code-block:: none

$ kinit [email protected]
[email protected]'s Password:
$ klistCredentials cache: FILE:/tmp/krb5cc_1000
$ kinit [email protected]
[email protected]'s Password:
$ klistCredentials cache: FILE:/tmp/krb5cc_1000
Principal: [email protected]

Issued Expires Principal
Feb 9 13:48:51 2013 Feb 9 23:48:51 2013 krbtgt/[email protected]
Feb 9 13:48:51 2013 Feb 9 23:48:51 2013 krbtgt/[email protected]

Now authenticate using the MongoDB URI. ``GSSAPI`` authenticates against the ``$external`` virtual database, so a database does not need to be specified in the URI. Note that the Kerberos principal *must* be URL-encoded:
Now authenticate using the MongoDB URI. ``GSSAPI`` authenticates against the ``$external`` virtual database,
so a database does not need to be specified in the URI. Note that the Kerberos principal *must* be URL-encoded:

Check failure on line 119 in source/docs-libmongoc/authentication.txt

View workflow job for this annotation

GitHub Actions / TDBX Vale rules 

[vale] reported by reviewdog 🐶
[MongoDB.ConciseTerms] 'must' is preferred over 'need to'.

Raw Output:
{"message": "[MongoDB.ConciseTerms] 'must' is preferred over 'need to'.", "location": {"path": "source/docs-libmongoc/authentication.txt", "range": {"start": {"line": 119, "column": 24}}}, "severity": "ERROR"}

.. code-block:: none

mongoc_client_t *client;
mongoc_client_t *client;

client = mongoc_client_new ("mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI");
client = mongoc_client_new ("mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI");

.. note::

``GSSAPI`` authenticates against the ``$external`` database, so specifying the authSource database is not required.
``GSSAPI`` authenticates against the ``$external`` database, so specifying the authSource database is not required.

The driver supports these GSSAPI properties:

* ``CANONICALIZE_HOST_NAME``: This might be required with Cyrus-SASL when the hosts report different hostnames than what is used in the Kerberos database. The default is "false".
* ``SERVICE_NAME``: Use a different service name than the default, "mongodb".
- ``CANONICALIZE_HOST_NAME``: This might be required with Cyrus-SASL when the hosts report different hostnames
than what is used in the Kerberos database. The default is "false".
- ``SERVICE_NAME``: Use a different service name than the default, "mongodb".

Set properties in the URL:

.. code-block:: none

mongoc_client_t *client;
mongoc_client_t *client;

client = mongoc_client_new ("mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI&"
"authMechanismProperties=SERVICE_NAME:other,CANONICALIZE_HOST_NAME:true");
client = mongoc_client_new ("mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI&"
"authMechanismProperties=SERVICE_NAME:other,CANONICALIZE_HOST_NAME:true");

If you encounter errors such as ``Invalid net address``, check if the application is behind a NAT (Network Address Translation) firewall. If so, create a ticket that uses ``forwardable`` and ``addressless`` Kerberos tickets. This can be done by passing ``-f -A`` to ``kinit``.

Expand Down

0 comments on commit 06baccd

Please sign in to comment.