diff --git a/README.md b/README.md index f1c52a4cb..c8cc37fe9 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,13 @@ A content repository for the Atlas Architecture Center documentation site. ## Report Issues To file issues or requests regarding the documentation, go to the -`Documentation Jira Project `_. +[Documentation Jira Project](https://jira.mongodb.org/browse/DOCS). ## License -All documentation is available under the terms of a `Creative Commons -License `_. +All documentation is available under the terms of a +[Creative Commons License](https://creativecommons.org/licenses/by-nc-sa/3.0/). -If you have any questions, please contact `docs@mongodb.com -`_. +If you have any questions, please contact [docs@mongodb.com](mailto:docs@mongodb.com). -- The MongoDB Documentation Team diff --git a/source/includes/complete-examples-go-sdk.rst b/source/includes/complete-examples-go-sdk.rst new file mode 100644 index 000000000..57c9d32ea --- /dev/null +++ b/source/includes/complete-examples-go-sdk.rst @@ -0,0 +1,7 @@ +.. cta-banner:: + :url: https://github.com/mongodb/atlas-architecture-go-sdk + :icon: Code + + See the example scripts from the Atlas SDK for Go project in one place + `in Github `__. + diff --git a/source/includes/complete-examples.rst b/source/includes/complete-examples-terraform.rst similarity index 100% rename from source/includes/complete-examples.rst rename to source/includes/complete-examples-terraform.rst diff --git a/source/includes/examples/generated-examples/main.snippet.get-logs-main.go b/source/includes/examples/generated-examples/main.snippet.get-logs-main.go new file mode 100644 index 000000000..750bceb0b --- /dev/null +++ b/source/includes/examples/generated-examples/main.snippet.get-logs-main.go @@ -0,0 +1,27 @@ +func main() { + ctx := context.Background() + + // Create an Atlas client authenticated using OAuth2 with service account credentials + client, _, config, err := auth.CreateAtlasClient() + if err != nil { + log.Fatalf("Failed to create Atlas client: %v", err) + } + + params := &admin.GetHostLogsApiParams{ + GroupId: config.ProjectID, + HostName: config.HostName, + LogName: "mongodb", // The type of log to get ("mongodb" or "mongos") + } + + logFileName, err := getHostLogs(ctx, *client, params) + if err != nil { + log.Fatalf("Failed to download logs: %v", err) + } + + plainTextLog := strings.TrimSuffix(logFileName, ".gz") + ".log" + if err := unzipGzFile(logFileName, plainTextLog); err != nil { + log.Fatalf("Failed to unzip log file: %v", err) + } + +} + diff --git a/source/includes/examples/generated-examples/main.snippet.get-logs.go b/source/includes/examples/generated-examples/main.snippet.get-logs.go new file mode 100644 index 000000000..ad6526192 --- /dev/null +++ b/source/includes/examples/generated-examples/main.snippet.get-logs.go @@ -0,0 +1,112 @@ +// See entire project at https://github.com/mongodb/atlas-architecture-go-sdk +package main + +import ( + "atlas-sdk-go/internal/auth" + "compress/gzip" + "context" + "fmt" + "io" + "log" + "os" + "strings" + + "go.mongodb.org/atlas-sdk/v20250219001/admin" +) + +func SafeClose(c io.Closer) { + if c != nil { + if err := c.Close(); err != nil { + log.Printf("Warning: failed to close resource: %v", err) + } + } +} + +// getHostLogs downloads a compressed .gz file that contains the MongoDB logs for +// the specified host in your project. +func getHostLogs(ctx context.Context, atlasClient admin.APIClient, params *admin.GetHostLogsApiParams) (string, error) { + logFileName := fmt.Sprintf("logs_%s_%s.gz", params.GroupId, params.HostName) + fmt.Printf("Fetching %s log for host %s in project %s\n", params.LogName, params.HostName, params.GroupId) + + if err := downloadLogs(ctx, atlasClient, params, logFileName); err != nil { + return "", err + } + + fmt.Printf("Logs saved to %s\n", logFileName) + return logFileName, nil +} + +func downloadLogs(ctx context.Context, atlasClient admin.APIClient, params *admin.GetHostLogsApiParams, filePath string) error { + resp, _, err := atlasClient.MonitoringAndLogsApi.GetHostLogsWithParams(ctx, params).Execute() + if err != nil { + return fmt.Errorf("fetch logs: %w", err) + } + defer SafeClose(resp) + + file, err := os.Create(filePath) + if err != nil { + return fmt.Errorf("create %q: %w", filePath, err) + } + defer SafeClose(file) + + if _, err := io.Copy(file, resp); err != nil { + return fmt.Errorf("write to %q: %w", filePath, err) + } + + return nil +} + +func unzipGzFile(srcPath, destPath string) error { + srcFile, err := os.Open(srcPath) + if err != nil { + return fmt.Errorf("open gz file: %w", err) + } + defer SafeClose(srcFile) + + gzReader, err := gzip.NewReader(srcFile) + if err != nil { + return fmt.Errorf("create gzip reader: %w", err) + } + defer SafeClose(gzReader) + + destFile, err := os.Create(destPath) + if err != nil { + return fmt.Errorf("create destination file: %w", err) + } + defer SafeClose(destFile) + + if _, err := io.Copy(destFile, gzReader); err != nil { + return fmt.Errorf("unzip copy error: %w", err) + } + + fmt.Printf("Unzipped logs to %s\n", destPath) + return nil +} + +func main() { + ctx := context.Background() + + // Create an Atlas client authenticated using OAuth2 with service account credentials + client, _, config, err := auth.CreateAtlasClient() + if err != nil { + log.Fatalf("Failed to create Atlas client: %v", err) + } + + params := &admin.GetHostLogsApiParams{ + GroupId: config.ProjectID, + HostName: config.HostName, + LogName: "mongodb", // The type of log to get ("mongodb" or "mongos") + } + + logFileName, err := getHostLogs(ctx, *client, params) + if err != nil { + log.Fatalf("Failed to download logs: %v", err) + } + + plainTextLog := strings.TrimSuffix(logFileName, ".gz") + ".log" + if err := unzipGzFile(logFileName, plainTextLog); err != nil { + log.Fatalf("Failed to unzip log file: %v", err) + } + +} + diff --git a/source/includes/examples/generated-examples/main.snippet.get-metrics-dev.go b/source/includes/examples/generated-examples/main.snippet.get-metrics-dev.go new file mode 100644 index 000000000..95ce8eaed --- /dev/null +++ b/source/includes/examples/generated-examples/main.snippet.get-metrics-dev.go @@ -0,0 +1,64 @@ +// See entire project at https://github.com/mongodb/atlas-architecture-go-sdk +package main + +import ( + "atlas-sdk-go/internal/auth" + "context" + "encoding/json" + "fmt" + "go.mongodb.org/atlas-sdk/v20250219001/admin" + "log" +) + +// getDiskMetrics fetches metrics for a specified disk partition in a project and prints results to the console +func getDiskMetrics(ctx context.Context, atlasClient admin.APIClient, params *admin.GetDiskMeasurementsApiParams) (*admin.ApiMeasurementsGeneralViewAtlas, error) { + + resp, _, err := atlasClient.MonitoringAndLogsApi.GetDiskMeasurementsWithParams(ctx, params).Execute() + if err != nil { + if apiError, ok := admin.AsError(err); ok { + return nil, fmt.Errorf("failed to get metrics for partition: %s (API error: %v)", err, apiError.GetDetail()) + } + return nil, fmt.Errorf("failed to get metrics: %w", err) + } + if resp == nil || resp.HasMeasurements() == false { + return nil, fmt.Errorf("no metrics found for partition %s in project %s", params.PartitionName, params.GroupId) + } + jsonData, err := json.MarshalIndent(resp, "", " ") + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + fmt.Println(string(jsonData)) + return resp, nil +} + +func main() { + ctx := context.Background() + + // Create an Atlas client authenticated using OAuth2 with service account credentials + atlasClient, _, config, err := auth.CreateAtlasClient() + if err != nil { + log.Fatalf("Failed to create Atlas client: %v", err) + } + + // Fetch disk metrics using the following parameters: + partitionName := "data" + diskMetricsGranularity := admin.PtrString("P1D") + diskMetricsPeriod := admin.PtrString("P1D") + diskMetrics := []string{ + "DISK_PARTITION_SPACE_FREE", "DISK_PARTITION_SPACE_USED", + } + + diskMeasurementsParams := &admin.GetDiskMeasurementsApiParams{ + GroupId: config.ProjectID, + ProcessId: config.ProcessID, + PartitionName: partitionName, + M: &diskMetrics, + Granularity: diskMetricsGranularity, + Period: diskMetricsPeriod, + } + _, err = getDiskMetrics(ctx, *atlasClient, diskMeasurementsParams) + if err != nil { + fmt.Printf("Error fetching disk metrics: %v", err) + } +} + diff --git a/source/includes/examples/generated-examples/main.snippet.get-metrics-main-dev.go b/source/includes/examples/generated-examples/main.snippet.get-metrics-main-dev.go new file mode 100644 index 000000000..4cd22c5b4 --- /dev/null +++ b/source/includes/examples/generated-examples/main.snippet.get-metrics-main-dev.go @@ -0,0 +1,31 @@ +func main() { + ctx := context.Background() + + // Create an Atlas client authenticated using OAuth2 with service account credentials + atlasClient, _, config, err := auth.CreateAtlasClient() + if err != nil { + log.Fatalf("Failed to create Atlas client: %v", err) + } + + // Fetch disk metrics using the following parameters: + partitionName := "data" + diskMetricsGranularity := admin.PtrString("P1D") + diskMetricsPeriod := admin.PtrString("P1D") + diskMetrics := []string{ + "DISK_PARTITION_SPACE_FREE", "DISK_PARTITION_SPACE_USED", + } + + diskMeasurementsParams := &admin.GetDiskMeasurementsApiParams{ + GroupId: config.ProjectID, + ProcessId: config.ProcessID, + PartitionName: partitionName, + M: &diskMetrics, + Granularity: diskMetricsGranularity, + Period: diskMetricsPeriod, + } + _, err = getDiskMetrics(ctx, *atlasClient, diskMeasurementsParams) + if err != nil { + fmt.Printf("Error fetching disk metrics: %v", err) + } +} + diff --git a/source/includes/examples/generated-examples/main.snippet.get-metrics-main-prod.go b/source/includes/examples/generated-examples/main.snippet.get-metrics-main-prod.go new file mode 100644 index 000000000..f07839ad4 --- /dev/null +++ b/source/includes/examples/generated-examples/main.snippet.get-metrics-main-prod.go @@ -0,0 +1,32 @@ +func main() { + ctx := context.Background() + + // Create an Atlas client authenticated using OAuth2 with service account credentials + atlasClient, _, config, err := auth.CreateAtlasClient() + if err != nil { + log.Fatalf("Failed to create Atlas client: %v", err) + } + + // Fetch process metrics using the following parameters: + processMetricGranularity := admin.PtrString("PT1H") + processMetricPeriod := admin.PtrString("P7D") + processMetrics := []string{ + "OPCOUNTER_INSERT", "OPCOUNTER_QUERY", "OPCOUNTER_UPDATE", "TICKETS_AVAILABLE_READS", + "TICKETS_AVAILABLE_WRITE", "CONNECTIONS", "QUERY_TARGETING_SCANNED_OBJECTS_PER_RETURNED", + "QUERY_TARGETING_SCANNED_PER_RETURNED", "SYSTEM_CPU_GUEST", "SYSTEM_CPU_IOWAIT", + "SYSTEM_CPU_IRQ", "SYSTEM_CPU_KERNEL", "SYSTEM_CPU_NICE", "SYSTEM_CPU_SOFTIRQ", + "SYSTEM_CPU_STEAL", "SYSTEM_CPU_USER", + } + hostMeasurementsParams := &admin.GetHostMeasurementsApiParams{ + GroupId: config.ProjectID, + ProcessId: config.ProcessID, + M: &processMetrics, + Granularity: processMetricGranularity, + Period: processMetricPeriod, + } + _, err = getProcessMetrics(ctx, *atlasClient, hostMeasurementsParams) + if err != nil { + fmt.Printf("Error fetching host process metrics: %v", err) + } +} + diff --git a/source/includes/examples/generated-examples/main.snippet.get-metrics-prod.go b/source/includes/examples/generated-examples/main.snippet.get-metrics-prod.go new file mode 100644 index 000000000..99f27d0f7 --- /dev/null +++ b/source/includes/examples/generated-examples/main.snippet.get-metrics-prod.go @@ -0,0 +1,67 @@ +// See entire project at https://github.com/mongodb/atlas-architecture-go-sdk +package main + +import ( + "atlas-sdk-go/internal/auth" + "context" + "encoding/json" + "fmt" + "go.mongodb.org/atlas-sdk/v20250219001/admin" + "log" +) + +// getProcessMetrics fetches metrics for a specified host process in a project and prints results to the console +func getProcessMetrics(ctx context.Context, atlasClient admin.APIClient, params *admin.GetHostMeasurementsApiParams) (*admin.ApiMeasurementsGeneralViewAtlas, error) { + fmt.Printf("Fetching metrics for host process %s in project %s", params.ProcessId, params.GroupId) + + resp, _, err := atlasClient.MonitoringAndLogsApi.GetHostMeasurementsWithParams(ctx, params).Execute() + if err != nil { + if apiError, ok := admin.AsError(err); ok { + return nil, fmt.Errorf("failed to get metrics for process in host: %s (API error: %v)", err, apiError.GetDetail()) + } + return nil, fmt.Errorf("failed to get metrics: %w", err) + } + + if resp == nil || resp.HasMeasurements() == false { + return nil, fmt.Errorf("no metrics found for host process %s in project %s", params.ProcessId, params.GroupId) + } + jsonData, err := json.MarshalIndent(resp, "", " ") + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + fmt.Println(string(jsonData)) + return resp, nil +} + +func main() { + ctx := context.Background() + + // Create an Atlas client authenticated using OAuth2 with service account credentials + atlasClient, _, config, err := auth.CreateAtlasClient() + if err != nil { + log.Fatalf("Failed to create Atlas client: %v", err) + } + + // Fetch process metrics using the following parameters: + processMetricGranularity := admin.PtrString("PT1H") + processMetricPeriod := admin.PtrString("P7D") + processMetrics := []string{ + "OPCOUNTER_INSERT", "OPCOUNTER_QUERY", "OPCOUNTER_UPDATE", "TICKETS_AVAILABLE_READS", + "TICKETS_AVAILABLE_WRITE", "CONNECTIONS", "QUERY_TARGETING_SCANNED_OBJECTS_PER_RETURNED", + "QUERY_TARGETING_SCANNED_PER_RETURNED", "SYSTEM_CPU_GUEST", "SYSTEM_CPU_IOWAIT", + "SYSTEM_CPU_IRQ", "SYSTEM_CPU_KERNEL", "SYSTEM_CPU_NICE", "SYSTEM_CPU_SOFTIRQ", + "SYSTEM_CPU_STEAL", "SYSTEM_CPU_USER", + } + hostMeasurementsParams := &admin.GetHostMeasurementsApiParams{ + GroupId: config.ProjectID, + ProcessId: config.ProcessID, + M: &processMetrics, + Granularity: processMetricGranularity, + Period: processMetricPeriod, + } + _, err = getProcessMetrics(ctx, *atlasClient, hostMeasurementsParams) + if err != nil { + fmt.Printf("Error fetching host process metrics: %v", err) + } +} + diff --git a/source/includes/examples/generated-examples/snippet.config.json b/source/includes/examples/generated-examples/snippet.config.json new file mode 100644 index 000000000..207e973c2 --- /dev/null +++ b/source/includes/examples/generated-examples/snippet.config.json @@ -0,0 +1,7 @@ +{ + "MONGODB_ATLAS_BASE_URL": "https://cloud.mongodb.com", + "ATLAS_ORG_ID": "32b6e34b3d91647abb20e7b8", + "ATLAS_PROJECT_ID": "67212db237c5766221eb6ad9", + "ATLAS_CLUSTER_NAME": "myCluster", + "ATLAS_PROCESS_ID": "myCluster-shard-00-00.ajlj3.mongodb.net:27017" +} diff --git a/source/monitoring-alerts.txt b/source/monitoring-alerts.txt index 628683d81..7097c671a 100644 --- a/source/monitoring-alerts.txt +++ b/source/monitoring-alerts.txt @@ -10,8 +10,13 @@ Guidance for {+service+} Monitoring and Alerts :name: genre :values: reference +.. facet:: + :name: programming_language + :values: go, shell + .. meta:: :description: Learn how to monitor and set up alerts on your Atlas cluster. + :keywords: code example, atlas sdk for go, terraform configuration, atlas cli .. contents:: On this page :local: @@ -461,8 +466,6 @@ When you configure this feature, {+service+} continually pushes logs from ``mong Automation Examples: {+service+} Monitoring and Logging ------------------------------------------------------- -.. include:: /includes/complete-examples.rst - The following examples demonstrate how to enable monitoring using |service| :ref:`tools for automation `. @@ -518,8 +521,55 @@ The following examples demonstrate how to enable monitoring using |service| .. include:: /includes/examples/cli/cli-example-download-logs.rst + .. tab:: Atlas Go SDK + :tabid: go-sdk + + .. include:: /includes/complete-examples-go-sdk.rst + + Before you can authenticate and run the example scripts using + the Atlas Go SDK, you must: + + - :ref:`Create an Atlas service account `. + Store your client ID and secret as environment variables by + running the following command in the terminal: + + .. code-block:: shell + + export MONGODB_ATLAS_SERVICE_ACCOUNT_ID="" + export MONGODB_ATLAS_SERVICE_ACCOUNT_SECRET="" + + - Set the following configuration variables in your Go project: + + .. literalinclude:: /includes/examples/generated-examples/snippet.config.json + :language: json + :caption: configs/config.json + + View Cluster Metrics + ~~~~~~~~~~~~~~~~~~~~ + + The following example script demonstrates how to retrieve the amount of + used and free space on the specified disk. This metric can be used + to determine if the system is running out of free space. + + .. literalinclude:: /includes/examples/generated-examples/main.snippet.get-metrics-dev.go + :language: go + :caption: get-cluster-metrics/main.go + + Download Logs + ~~~~~~~~~~~~~ + + The following example script demonstrates how to download and + unzip a compressed file that contains the + MongoDB logs for the specified host in your Atlas project: + + .. literalinclude:: /includes/examples/generated-examples/main.snippet.get-logs.go + :language: go + :caption: get-logs/main.go + .. tab:: Terraform - :tabid: terraform + :tabid: terraform + + .. include:: /includes/complete-examples-terraform.rst Before you can create resources with Terraform, you must: @@ -529,7 +579,7 @@ The following examples demonstrate how to enable monitoring using |service| Store your |api| key as environment variables by running the following command in the terminal: - .. code-block:: + .. code-block:: shell export MONGODB_ATLAS_PUBLIC_KEY="" export MONGODB_ATLAS_PRIVATE_KEY="" @@ -580,18 +630,18 @@ The following examples demonstrate how to enable monitoring using |service| Run the sample command to retrieve the following metrics: - - OPCOUNTERS - to monitor the amount of queries, updates, inserts, + - OPCOUNTERS - Monitor the amount of queries, updates, inserts, and deletes occurring at peak load and ensure that load doesn't - increase unexpectedly. - - TICKETS - to ensure that the number of allowed concurrent reads - and writes doesn't lower much, or frequently. - - CONNECTIONS - to ensure that the number of sockets used for - heartbeats and replication between members isn't above the - set limit. - - QUERY TARGETING - to ensure that number of keys and documents + increase unexpectedly. + - TICKETS - Ensure that the number of allowed concurrent reads + and writes doesn't lower much, or frequently. + - CONNECTIONS - Ensure that the number of sockets used for + heartbeats and replication between members isn't above the + set limit. + - QUERY TARGETING - Ensure that number of keys and documents scanned to the number of documents returned, averaged by second, - are't too high. - - SYSTEM CPU - to ensure that the CPU usage is steady. + are't too high. + - SYSTEM CPU - Ensure that the CPU usage is steady. .. include:: /includes/examples/cli/staging-prod/cli-example-metrics-processes-stagingprod.rst @@ -620,9 +670,70 @@ The following examples demonstrate how to enable monitoring using |service| .. include:: /includes/examples/cli/cli-example-download-logs.rst + .. tab:: Atlas Go SDK + :tabid: go-sdk + + .. include:: /includes/complete-examples-go-sdk.rst + + Before you can authenticate and run the example scripts using + the Atlas Go SDK, you must: + + - :ref:`Create an Atlas service account `. + Store your client ID and secret as environment variables by + running the following command in the terminal: + + .. code-block:: shell + + export MONGODB_ATLAS_SERVICE_ACCOUNT_ID="" + export MONGODB_ATLAS_SERVICE_ACCOUNT_SECRET="" + + - Set the following configuration variables in your Go project: + + .. literalinclude:: /includes/examples/generated-examples/snippet.config.json + :language: json + :caption: configs/config.json + + For more information on authenticating and creating a client, see + the complete Atlas SDK for Go example project `in GitHub `__. + + View Cluster Metrics + ~~~~~~~~~~~~~~~~~~~~ + + The following example script demonstrates how to retrieve the following metrics: + + - OPCOUNTERS - Monitor the amount of queries, updates, inserts, + and deletes occurring at peak load and ensure that load doesn't + increase unexpectedly. + - TICKETS - Ensure that the number of allowed concurrent reads + and writes doesn't lower much, or frequently. + - CONNECTIONS - Ensure that the number of sockets used for + heartbeats and replication between members isn't above the + set limit. + - QUERY TARGETING - Ensure that number of keys and documents + scanned to the number of documents returned, averaged by second, + are't too high. + - SYSTEM CPU - Ensure that the CPU usage is steady. + + ..literalinclude:: /includes/examples/generated-examples/main.snippet.get-metrics-prod.go + :language: go + :caption: get-disk-metrics/main.go + + Download Logs + ~~~~~~~~~~~~~ + + The following example script demonstrates how to download and + unzip a compressed file that contains the + MongoDB logs for the specified host in your Atlas project: + + .. literalinclude:: /includes/examples/generated-examples/main.snippet.get-logs.go + :language: go + :caption: get-logs/main.go + .. tab:: Terraform :tabid: terraform + .. include:: /includes/complete-examples-terraform.rst + Before you can create resources with Terraform, you must: - :ref:`Create your paying organization @@ -631,7 +742,7 @@ The following examples demonstrate how to enable monitoring using |service| Store your |api| key as environment variables by running the following command in the terminal: - .. code-block:: + .. code-block:: shell export MONGODB_ATLAS_PUBLIC_KEY="" export MONGODB_ATLAS_PRIVATE_KEY=""