diff --git a/.readme-partials.yaml b/.readme-partials.yaml new file mode 100644 index 000000000..d96ef9b4e --- /dev/null +++ b/.readme-partials.yaml @@ -0,0 +1,106 @@ +custom_content: | + #### Creating an authorized service object + To make authenticated requests to Stackdriver Logging, you must create a service object with + credentials. You can then make API calls by calling methods on the Logging service object. The + simplest way to authenticate is to use + [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). + These credentials are automatically inferred from your environment, so you only need the following + code to create your service object: + + ```java + import com.google.cloud.logging.Logging; + import com.google.cloud.logging.LoggingOptions; + + LoggingOptions options = LoggingOptions.getDefaultInstance(); + try(Logging logging = options.getService()) { + // use logging here + } + ``` + + For other authentication options, see the + [Authentication](https://github.com/googleapis/google-cloud-java#authentication) page. + + #### Creating a metric + With Logging you can create logs-based metrics. Logs-based metrics allow to keep track of the number + of log messages associated to specific events. Add the following imports at the top of your file: + + ```java + import com.google.cloud.logging.Metric; + import com.google.cloud.logging.MetricInfo; + ``` + Then, to create the metric, use the following code: + + ```java + MetricInfo metricInfo = MetricInfo.newBuilder("test-metric", "severity >= ERROR") + .setDescription("Log entries with severity higher or equal to ERROR") + .build(); + logging.create(metricInfo); + ``` + + #### Writing log entries + With Logging you can also write custom log entries. Add the following imports at the top of your + file: + ```java + import com.google.cloud.MonitoredResource; + import com.google.cloud.logging.LogEntry; + import com.google.cloud.logging.Logging; + import com.google.cloud.logging.Payload.StringPayload; + + import java.util.Collections; + ``` + Then, to write the log entries, use the following code: + ```java + LogEntry firstEntry = LogEntry.newBuilder(StringPayload.of("message")) + .setLogName("test-log") + .setResource(MonitoredResource.newBuilder("global") + .addLabel("project_id", options.getProjectId()) + .build()) + .build(); + logging.write(Collections.singleton(firstEntry)); + ``` + + #### Listing log entries + With Logging you can also list log entries that have been previously written. Add the following + imports at the top of your file: + ```java + import com.google.cloud.Page; + import com.google.cloud.logging.LogEntry; + import com.google.cloud.logging.Logging.EntryListOption; + ``` + Then, to list the log entries, use the following code: + + ``` java + Page entries = logging.listLogEntries( + EntryListOption.filter("logName=projects/" + options.getProjectId() + "/logs/test-log")); + Iterator entryIterator = entries.iterateAll().iterator(); + while (entryIterator.hasNext()) { + System.out.println(entryIterator.next()); + } + ``` + + #### Add a Stackdriver Logging handler to a logger + You can also register a `LoggingHandler` to a `java.util.logging.Logger` that publishes log entries + to Stackdriver Logging. Given the following logger: + ```java + private final static Logger LOGGER = Logger.getLogger(MyClass.class.getName()); + ``` + You can register a `LoggingHandler` with the code: + ```java + LoggingHandler.addHandler(LOGGER, new LoggingHandler()); + ``` + After that, logs generated using `LOGGER` will be also directed to Stackdriver Logging. + + Notice that you can also register a `LoggingHandler` via the `logging.properties` configuration + file. Adding, for instance, the following line: + ``` + com.google.cloud.examples.logging.snippets.AddLoggingHandler.handlers=com.google.cloud.logging.LoggingHandler + ``` + #### Complete source code + + In + [CreateAndListMetrics.java](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/CreateAndListMetrics.java), + [WriteAndListLogEntries.java](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/WriteAndListLogEntries.java) + and + [AddLoggingHandler.java](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/AddLoggingHandler.java) + we put together all the code shown above into three programs. The programs assume that you are + running on Compute Engine or from your own desktop. \ No newline at end of file diff --git a/.repo-metadata.json b/.repo-metadata.json index b202ae4b9..680b47911 100644 --- a/.repo-metadata.json +++ b/.repo-metadata.json @@ -2,12 +2,14 @@ "name": "logging", "name_pretty": "Stackdriver Logging", "product_documentation": "https://cloud.google.com/logging/docs", - "client_documentation": "https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/logging/package-summary.html", + "client_documentation": "https://googleapis.dev/java/google-cloud-logging/latest/", "issue_tracker": "https://issuetracker.google.com/savedsearches/559764", "release_level": "ga", "language": "java", "repo": "googleapis/java-logging", "repo_short": "java-logging", "distribution_name": "com.google.cloud:google-cloud-logging", - "api_id": "logging.googleapis.com" + "api_id": "logging.googleapis.com", + "transport": "grpc", + "api_description": "allows you to store, search, analyze, monitor, and alert on log data and events from Google Cloud and Amazon Web Services. Using the BindPlane service, you can also collect this data from over 150 common application components, on-premises systems, and hybrid cloud systems. BindPlane is included with your Google Cloud project at no additional cost." } \ No newline at end of file diff --git a/README.md b/README.md index b9a1dee1e..987e824e7 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,49 @@ -Google Cloud Java Client for Logging -==================================== +# Google Stackdriver Logging Client for Java -Java idiomatic client for [Stackdriver Logging][stackdriver-logging]. +Java idiomatic client for [Stackdriver Logging][product-docs]. -[![Kokoro CI](http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/master.svg)](http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/master.html) -[![Maven](https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-logging.svg)]( https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-logging.svg) -[![Codacy Badge](https://api.codacy.com/project/badge/grade/9da006ad7c3a4fe1abd142e77c003917)](https://www.codacy.com/app/mziccard/google-cloud-java) +[![Maven][maven-version-image]][maven-version-link] +![Stability][stability-image] -- [Product Documentation][logging-product-docs] -- [Client Library Documentation][logging-client-lib-docs] +- [Product Documentation][product-docs] +- [Client Library Documentation][javadocs] -Quickstart ----------- -If you are using Maven with Bom, Add this to your pom.xml file. +## Quickstart + +If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file ```xml - - - - com.google.cloud - libraries-bom - 3.3.0 - pom - import - - + + + com.google.cloud + libraries-bom + 4.1.0 + pom + import + + - - com.google.cloud - google-cloud-logging - - + + + com.google.cloud + google-cloud-logging + + ``` + [//]: # ({x-version-update-start:google-cloud-logging:released}) -If you are using Maven without Bom, Add this to your dependencies. + +If you are using Maven without BOM, add this to your dependencies: + ```xml - com.google.cloud google-cloud-logging 1.100.0 - ``` + If you are using Gradle, add this to your dependencies ```Groovy compile 'com.google.cloud:google-cloud-logging:1.100.0' @@ -54,48 +54,34 @@ libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "1.100.0" ``` [//]: # ({x-version-update-end}) -Example Application -------------------- -[`LoggingExample`](../../google-cloud-examples/src/main/java/com/google/cloud/examples/logging/LoggingExample.java) -is a simple command line interface that provides some of Stackdriver Logging's functionality. Read -more about using the application on the -[`LoggingExample` docs page](https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/examples/logging/LoggingExample.html). - -Authentication --------------- - -See the [Authentication](https://github.com/googleapis/google-cloud-java#authentication) section in the base directory's README. - -About Stackdriver Logging --------------------------- - -[Stackdriver Logging][stackdriver-logging] allows you to store, search, analyze, monitor, and alert -on log data and events from Google Cloud Platform and Amazon Web Services (AWS). Logging is a -fully-managed service that performs at scale and can ingest application and system log data from -thousands of VMs. Even better, you can analyze all that log data in real-time. - -See the [Stackdriver Logging docs][stackdriver-logging-quickstart] for more details on how to -activate Logging for your project. - -See the [Logging client library docs][logging-client-lib-docs] to learn how to interact with the -Stackdriver Logging using this Client Library. - -Getting Started ---------------- -#### Prerequisites -For this tutorial, you will need a -[Google Developers Console](https://console.developers.google.com/) project with the Logging API -enabled. You will need to [enable billing](https://support.google.com/cloud/answer/6158867?hl=en) to -use Stackdriver Logging. -[Follow these instructions](https://cloud.google.com/resource-manager/docs/creating-managing-projects) to get your -project set up. You will also need to set up the local development environment by [installing the -Google Cloud SDK](https://cloud.google.com/sdk/) and running the following commands in command line: +## Authentication + +See the [Authentication][authentication] section in the base directory's README. + +## Getting Started + +### Prerequisites + +You will need a [Google Cloud Platform Console][developer-console] project with the Stackdriver Logging [API enabled][enable-api]. + +[Follow these instructions][create-project] to get your project set up. You will also need to set up the local development environment by +[installing the Google Cloud SDK][cloud-sdk] and running the following commands in command line: `gcloud auth login` and `gcloud config set project [YOUR PROJECT ID]`. -#### Installation and setup +### Installation and setup + You'll need to obtain the `google-cloud-logging` library. See the [Quickstart](#quickstart) section to add `google-cloud-logging` as a dependency in your code. +## About Stackdriver Logging + + +[Stackdriver Logging][product-docs] allows you to store, search, analyze, monitor, and alert on log data and events from Google Cloud and Amazon Web Services. Using the BindPlane service, you can also collect this data from over 150 common application components, on-premises systems, and hybrid cloud systems. BindPlane is included with your Google Cloud project at no additional cost. + +See the [Stackdriver Logging client library docs][javadocs] to learn how to +use this Stackdriver Logging Client Library. + + #### Creating an authorized service object To make authenticated requests to Stackdriver Logging, you must create a service object with credentials. You can then make API calls by calling methods on the Logging service object. The @@ -195,58 +181,80 @@ com.google.cloud.examples.logging.snippets.AddLoggingHandler.handlers=com.google #### Complete source code In -[CreateAndListMetrics.java](../../google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/CreateAndListMetrics.java), -[WriteAndListLogEntries.java](../../google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/WriteAndListLogEntries.java) +[CreateAndListMetrics.java](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/CreateAndListMetrics.java), +[WriteAndListLogEntries.java](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/WriteAndListLogEntries.java) and -[AddLoggingHandler.java](../../google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/AddLoggingHandler.java) +[AddLoggingHandler.java](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-examples/src/main/java/com/google/cloud/examples/logging/snippets/AddLoggingHandler.java) we put together all the code shown above into three programs. The programs assume that you are running on Compute Engine or from your own desktop. -Transport ---------- -Logging uses gRPC for the transport layer. -Java Versions -------------- - -Java 7 or above is required for using this client. +## Troubleshooting -Testing -------- +To get help, follow the instructions in the [shared Troubleshooting document][troubleshooting]. -This library has tools to help make tests for code using Stackdriver Logging. +## Transport -See [TESTING] to read more about testing. +Stackdriver Logging uses gRPC for the transport layer. -Versioning ----------- +## Java Versions -This library follows [Semantic Versioning](http://semver.org/). - -It is currently in major version one (``1.y.z``), which means that the public API should be considered stable. - -Contributing ------------- - -Contributions to this library are always welcome and highly encouraged. +Java 7 or above is required for using this client. -See `google-cloud`'s [CONTRIBUTING] documentation and the [shared documentation](https://github.com/googleapis/google-cloud-common/blob/master/contributing/readme.md#how-to-contribute-to-gcloud) for more information on how to get started. +## Versioning -Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more information. +This library follows [Semantic Versioning](http://semver.org/). -License -------- -Apache 2.0 - See [LICENSE] for more information. +## Contributing -[CONTRIBUTING]:https://github.com/googleapis/google-cloud-java/blob/master/CONTRIBUTING.md -[code-of-conduct]:https://github.com/googleapis/google-cloud-java/blob/master/CODE_OF_CONDUCT.md#contributor-code-of-conduct -[LICENSE]: https://github.com/googleapis/google-cloud-java/blob/master/LICENSE -[TESTING]: https://github.com/googleapis/google-cloud-java/blob/master/TESTING.md#testing-code-that-uses-logging +Contributions to this library are always welcome and highly encouraged. -[stackdriver-logging]: https://cloud.google.com/logging/ -[stackdriver-logging-quickstart]: https://cloud.google.com/logging/docs/quickstart-sdk -[logging-product-docs]: https://cloud.google.com/logging/docs/ -[logging-client-lib-docs]: https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/logging/package-summary.html +See [CONTRIBUTING][contributing] for more information how to get started. + +Please note that this project is released with a Contributor Code of Conduct. By participating in +this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more +information. + +## License + +Apache 2.0 - See [LICENSE][license] for more information. + +## CI Status + +Java Version | Status +------------ | ------ +Java 7 | [![Kokoro CI][kokoro-badge-image-1]][kokoro-badge-link-1] +Java 8 | [![Kokoro CI][kokoro-badge-image-2]][kokoro-badge-link-2] +Java 8 OSX | [![Kokoro CI][kokoro-badge-image-3]][kokoro-badge-link-3] +Java 8 Windows | [![Kokoro CI][kokoro-badge-image-4]][kokoro-badge-link-4] +Java 11 | [![Kokoro CI][kokoro-badge-image-5]][kokoro-badge-link-5] + +[product-docs]: https://cloud.google.com/logging/docs +[javadocs]: https://googleapis.dev/java/google-cloud-logging/latest/ +[kokoro-badge-image-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java7.svg +[kokoro-badge-link-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java7.html +[kokoro-badge-image-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java8.svg +[kokoro-badge-link-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java8.html +[kokoro-badge-image-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java8-osx.svg +[kokoro-badge-link-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java8-osx.html +[kokoro-badge-image-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java8-win.svg +[kokoro-badge-link-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java8-win.html +[kokoro-badge-image-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java11.svg +[kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-logging/java11.html +[stability-image]: https://img.shields.io/badge/stability-ga-green +[maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-logging.svg +[maven-version-link]: https://search.maven.org/search?q=g:com.google.cloud%20AND%20a:google-cloud-logging&core=gav +[authentication]: https://github.com/googleapis/google-cloud-java#authentication +[developer-console]: https://console.developers.google.com/ +[create-project]: https://cloud.google.com/resource-manager/docs/creating-managing-projects +[cloud-sdk]: https://cloud.google.com/sdk/ +[troubleshooting]: https://github.com/googleapis/google-cloud-common/blob/master/troubleshooting/readme.md#troubleshooting +[contributing]: https://github.com/googleapis/java-logging/blob/master/CONTRIBUTING.md +[code-of-conduct]: https://github.com/googleapis/java-logging/blob/master/CODE_OF_CONDUCT.md#contributor-code-of-conduct +[license]: https://github.com/googleapis/java-logging/blob/master/LICENSE + +[enable-api]: https://console.cloud.google.com/flows/enableapi?apiid=logging.googleapis.com +[libraries-bom]: https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM \ No newline at end of file diff --git a/synth.metadata b/synth.metadata index f6289ac55..0b8b16f7a 100644 --- a/synth.metadata +++ b/synth.metadata @@ -1,13 +1,6 @@ { "updateTime": "2020-02-24T22:58:54.590074Z", "sources": [ - { - "generator": { - "name": "artman", - "version": "0.45.1", - "dockerImage": "googleapis/artman@sha256:36956ca6a4dc70a59de5d5d0fd35061b050bb56884516f0898f46d8220f25738" - } - }, { "generator": { "name": "artman", diff --git a/synth.py b/synth.py index f212374be..aa141bc5a 100644 --- a/synth.py +++ b/synth.py @@ -26,14 +26,11 @@ for version in versions: library = java.gapic_library( - service=service, - version=version, - config_pattern=config_pattern, - package_pattern='com.google.{service}.{version}' + service=service, + version=version, + config_pattern=config_pattern, + package_pattern='com.google.{service}.{version}', + gapic=gapic, ) -common_templates = gcp.CommonTemplates() -templates = common_templates.java_library() -s.copy(templates, excludes=[ - 'README.md', -]) \ No newline at end of file +java.common_templates()