[monitor] azingest (#21155)

eng/config.json

@@ -97,6 +97,10 @@
             "Name": "monitor/azquery",
             "CoverageGoal": 0.85
         },
+        {
+            "Name": "monitor/azingest",
+            "CoverageGoal": 0.75
+        },
         {
             "Name": "security/keyvault/azadmin",
             "CoverageGoal": 0.80

sdk/monitor/azingest/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Release History
+
+## 0.1.0 (2023-07-17)
+* This is the initial release of the `azingest` library

sdk/monitor/azingest/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

sdk/monitor/azingest/README.md

@@ -0,0 +1,119 @@
+# Azure Monitor Ingestion client module for Go
+
+The Azure Monitor Ingestion client module is used to send custom logs to [Azure Monitor][azure_monitor_overview] using the [Logs Ingestion API][ingestion_overview].
+
+This library allows you to send data from virtually any source to supported built-in tables or to custom tables that you create in Log Analytics workspaces. You can even extend the schema of built-in tables with custom columns.
+
+Source code | Package (pkg.go.dev) | [Product documentation][azure_monitor_overview] | Samples
+
+## Getting started
+
+### Prerequisites
+
+* A supported Go version (the Azure SDK supports the two most recent Go releases)
+* An [Azure subscription][azure_subscription]
+* An [Azure Log Analytics workspace][azure_monitor_create_using_portal]
+* A [Data Collection Endpoint][data_collection_endpoint]
+* A [Data Collection Rule][data_collection_rule]
+
+### Install the package
+
+Install the `azingest` and `azidentity` modules with `go get`:
+
+```bash
+go get github.com/Azure/azure-sdk-for-go/sdk/monitor/azingest
+go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
+```
+
+The [azidentity][azure_identity] module is used for Azure Active Directory authentication while creating the client.
+
+### Authentication
+
+An authenticated client object is required to upload logs. The examples demonstrate using [azidentity.NewDefaultAzureCredential][default_cred_ref] to authenticate; however, the client accepts any [azidentity][azure_identity] credential. See the [azidentity][azure_identity] documentation for more information about other credential types.
+
+#### Create a client
+
+Example client
+
+## Key concepts
+
+### Data Collection Endpoint
+
+Data Collection Endpoints (DCEs) allow you to uniquely configure ingestion settings for Azure Monitor. [This article][data_collection_endpoint] provides an overview of data collection endpoints including their contents and structure and how you can create and work with them.
+
+### Data Collection Rule
+
+Data collection rules (DCR) define data collected by Azure Monitor and specify how and where that data should be sent or stored. The REST API call must specify a DCR to use. A single DCE can support multiple DCRs, so you can specify a different DCR for different sources and target tables.
+
+The DCR must understand the structure of the input data and the structure of the target table. If the two don't match, it can use a transformation to convert the source data to match the target table. You may also use the transform to filter source data and perform any other calculations or conversions.
+
+For more information, see [Data collection rules in Azure Monitor][data_collection_rule], and see [this article][data_collection_rule_structure] for details about a DCR's structure. For information on how to retrieve a DCR ID, see [this tutorial][data_collection_rule_tutorial].
+
+### Log Analytics workspace tables
+
+Custom logs can send data to any custom table that you create and to certain built-in tables in your Log Analytics workspace. The target table must exist before you can send data to it. The following built-in tables are currently supported:
+
+- [CommonSecurityLog](https://learn.microsoft.com/azure/azure-monitor/reference/tables/commonsecuritylog)
+- [SecurityEvents](https://learn.microsoft.com/azure/azure-monitor/reference/tables/securityevent)
+- [Syslog](https://learn.microsoft.com/azure/azure-monitor/reference/tables/syslog)
+- [WindowsEvents](https://learn.microsoft.com/azure/azure-monitor/reference/tables/windowsevent)
+
+### Logs retrieval
+
+The logs that were uploaded using this module can be queried using the [azquery][azure_monitor_query] module (Azure Monitor Query).
+
+## Examples
+
+Get started with our examples.
+
+## Troubleshooting
+
+### Error Handling
+
+All methods which send HTTP requests return `*azcore.ResponseError` when these requests fail. `ResponseError` has error details and the raw response from Monitor Query.
+
+### Logging
+
+This module uses the logging implementation in `azcore`. To turn on logging for all Azure SDK modules, set `AZURE_SDK_GO_LOGGING` to `all`. By default, the logger writes to stderr. Use the `azcore/log` package to control log output. For example, logging only HTTP request and response events, and printing them to stdout:
+
+```go
+import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
+
+// Print log events to stdout
+azlog.SetListener(func(cls azlog.Event, msg string) {
+	fmt.Println(msg)
+})
+
+// Includes only requests and responses in credential logs
+azlog.SetEvents(azlog.EventRequest, azlog.EventResponse)
+```
+
+## Next steps
+
+To learn more about Azure Monitor, see the [Azure Monitor service documentation][azure_monitor_overview].
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments.
+
+<!-- LINKS -->
+[azure_identity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity
+[azure_monitor_create_using_portal]: https://learn.microsoft.com/azure/azure-monitor/logs/quick-create-workspace
+[azure_monitor_overview]: https://learn.microsoft.com/azure/azure-monitor/
+[azure_monitor_query]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/monitor/azquery
+[azure_subscription]: https://azure.microsoft.com/free/
+[data_collection_endpoint]: https://learn.microsoft.com/azure/azure-monitor/essentials/data-collection-endpoint-overview
+[data_collection_rule]: https://learn.microsoft.com/azure/azure-monitor/essentials/data-collection-rule-overview
+[data_collection_rule_structure]: https://learn.microsoft.com/azure/azure-monitor/essentials/data-collection-rule-structure
+[data_collection_rule_tutorial]: https://learn.microsoft.com/azure/azure-monitor/logs/tutorial-logs-ingestion-portal#collect-information-from-the-dcr
+[default_cred_ref]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/azidentity#defaultazurecredential
+[ingestion_overview]: https://learn.microsoft.com/azure/azure-monitor/logs/logs-ingestion-api-overview
+
+[cla]: https://cla.microsoft.com
+[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
+[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
+[coc_contact]: mailto:[email protected]

sdk/monitor/azingest/assets.json

@@ -0,0 +1,6 @@
+{
+  "AssetsRepo": "Azure/azure-sdk-assets",
+  "AssetsRepoPrefixPath": "go",
+  "TagPrefix": "go/monitor/azingest",
+  "Tag": "go/monitor/azingest_1c9fcb94ed"
+}

sdk/monitor/azingest/autorest.md

@@ -0,0 +1,60 @@
+## Go
+
+```yaml
+title: MonitorIngestionClient
+description: Azure Monitor Ingestion Go Client
+generated-metadata: false
+
+clear-output-folder: false
+export-clients: true
+go: true
+input-file: https://github.com/Azure/azure-rest-api-specs/blob/f07297ce913bfc911470a86436e73c9aceec0587/specification/monitor/data-plane/ingestion/stable/2023-01-01/DataCollectionRules.json
+license-header: MICROSOFT_MIT_NO_VERSION
+module: github.com/Azure/azure-sdk-for-go/sdk/monitor/azingest
+openapi-type: "data-plane"
+output-folder: ../azingest
+override-client-name: Client
+security: "AADToken"
+use: "@autorest/[email protected]"
+version: "^3.0.0"
+rawjson-as-bytes: true
+
+directive:
+  # delete unused model
+  - remove-model: PendingCertificateSigningRequestResult
+
+  # remove x-ms-client-request-id, it's added in a pipeline policy
+  - where-operation: Upload
+    remove-parameter:
+      in: header
+      name: x-ms-client-request-id
+
+  # rename parameter from "body" to "logs", "stream" to "streamName"
+  - from: swagger-document
+    where: $.paths..parameters..[?(@.name=='body')]
+    transform: $["x-ms-client-name"] = "logs"
+  - from: swagger-document
+    where: $.paths..parameters..[?(@.name=='stream')]
+    transform: $["x-ms-client-name"] = "streamName"
+
+ # delete unused error models
+  - from: models.go
+    where: $
+    transform: return $.replace(/(?:\/\/.*\s)+type (?:ErrorResponse|ErrorDetail|ErrorAdditionalInfo).+\{(?:\s.+\s)+\}\s/g, "");
+
+  # delete client name prefix from method options and response types
+  - from:
+      - client.go
+      - models.go
+      - response_types.go
+    where: $
+    transform: return $.replace(/Client(\w+)((?:Options|Response))/g, "$1$2");
+
+  # update doc comments
+  - from: swagger-document
+    where: $.paths..parameters..[?(@.name=='Content-Encoding')]
+    transform: $["description"] = "If the bytes of the \"logs\" parameter are already gzipped, set ContentEncoding to \"gzip\""
+  - from: swagger-document
+    where: $.paths./dataCollectionRules/{ruleId}/streams/{stream}.post
+    transform: $["description"] = "Ingestion API used to directly ingest data using Data Collection Rules. Maximum size of of API call is 1 MB."
+```

sdk/monitor/azingest/build.go

@@ -0,0 +1,12 @@
+//go:build go1.18
+// +build go1.18
+
+//go:generate autorest ./autorest.md
+//go:generate rm ./models_serde.go
+//go:generate rm ./constants.go
+//go:generate gofmt -w .
+
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+
+package azingest

sdk/monitor/azingest/ci.yml

@@ -0,0 +1,30 @@
+# NOTE: Please refer to https://aka.ms/azsdk/engsys/ci-yaml before editing this file.
+trigger:
+  branches:
+    include:
+    - main
+    - feature/*
+    - hotfix/*
+    - release/*
+  paths:
+    include:
+    - sdk/monitor/azingest
+
+pr:
+  branches:
+    include:
+    - main
+    - feature/*
+    - hotfix/*
+    - release/*
+  paths:
+    include:
+    - sdk/monitor/azingest
+
+
+stages:
+- template: /eng/pipelines/templates/jobs/archetype-sdk-client.yml
+  parameters:
+    ServiceDirectory: 'monitor/azingest'
+    RunLiveTests: true
+    SupportedClouds: 'Public,UsGov,China'