From 124e5fe8f1cd37febdc5b57285579647ca2aade8 Mon Sep 17 00:00:00 2001 From: Yoshi Yamaguchi Date: Thu, 22 Aug 2024 23:50:14 +0900 Subject: [PATCH 1/3] [ja] add Japanese translation of quick start of collector (#4879) --- content/ja/docs/collector/quick-start.md | 126 +++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 content/ja/docs/collector/quick-start.md diff --git a/content/ja/docs/collector/quick-start.md b/content/ja/docs/collector/quick-start.md new file mode 100644 index 000000000000..f6328c9fb7ac --- /dev/null +++ b/content/ja/docs/collector/quick-start.md @@ -0,0 +1,126 @@ +--- +title: クイックスタート +description: コレクターをセットアップとテレメトリーの収集をすぐに始めてみましょう！ +default_lang_commit: 78f1d31 +--- + + + +OpenTelemetryコレクターは、[トレース](/docs/concepts/signals/traces/)、[メトリクス](/docs/concepts/signals/metrics/)、[ログ](/docs/concepts/signals/logs/)を受け取り、テレメトリーを処理し、そのコンポーネントを使用してさまざまなオブザーバビリティバックエンドにエクスポートします。 +コレクターの概念的な概要については、[コレクター](/docs/collector)のページを参照してください。 + +本記事でたった5分で次の内容を学習できます。 + +- OpenTelemetryコレクターをセットアップして実行する +- テレメトリーを送信し、コレクターによって処理されるのを確認する + +## 事前要件 + +開発環境が以下の要件を満たしていることを確認してください。 +このページでは `bash` を使っていると仮定しています。 +お好みのシェルに合わせて、設定やコマンドを変更してください。 + +- [Docker](https://www.docker.com/)、あるいは他の互換コンテナランタイム +- [Go](https://go.dev/) 1.20以上 +- [`GOBIN` 環境変数][gobin]が設定されていること。もし設定されていなければ、適切に設定してください。次は一例です[^1]。 + ```sh + export GOBIN=${GOBIN:-$(go env GOPATH)/bin} + ``` + +[^1]: 詳細については、Goの公式サイトにある[Your first program](https://go.dev/doc/code#Command)のドキュメントを参照してください。 + +## 環境の設定 + +1. OpenTelemetryコレクターのDockerイメージをプルします。 + + ```sh + docker pull otel/opentelemetry-collector:{{% param vers %}} + ``` + +2. [telemetrygen]ユーティリティをインストールします。 + + ```sh + go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest + ``` + + このユーティリティは[トレース][traces]、[メトリクス][metrics]、[ログ][logs]を生成するクライアントをシミュレートできます。 + +## テレメトリーの生成と収集 + +3. コレクターを起動します。 + + ```sh + docker run \ + -p 127.0.0.1:4317:4317 \ + -p 127.0.0.1:55679:55679 \ + otel/opentelemetry-collector:{{% param vers %}} \ + 2>&1 | tee collector-output.txt # 補足的に出力をteeして後で検索しやすくする + ``` + +4. 別のターミナル窓でサンプルのトレースを生成します。 + + ```sh + $GOBIN/telemetrygen traces --otlp-insecure --traces 3 + ``` + + ユーティリティによって生成された出力の中に、トレースが生成されたことのログが表示されるはずです。 + + ```text + 2024-01-16T14:33:15.692-0500 INFO traces/worker.go:99 traces generated {"worker": 0, "traces": 3} + 2024-01-16T14:33:15.692-0500 INFO traces/traces.go:58 stop the batch span processor + ``` + + 関連する出力を簡単に見るには、フィルタリングすると良いでしょう。 + + ```sh + $GOBIN/telemetrygen traces --otlp-insecure \ + --traces 3 2>&1 | grep -E 'start|traces|stop' + ``` + +5. コレクターコンテナを実行しているターミナル窓に、以下の例に示すようなトレースを取り込んだ様子が表示されるはずです。 + + ```console + $ grep -E '^Span|(ID|Name|Kind|time|Status \w+)\s+:' ./collector-output.txt + Span #0 + Trace ID : f30faffbde5fcf71432f89da1bf7bc14 + Parent ID : 6f1ff7f9cf4ec1c7 + ID : 8d1e820c1ac57337 + Name : okey-dokey + Kind : Server + Start time : 2024-01-16 14:13:54.585877 +0000 UTC + End time : 2024-01-16 14:13:54.586 +0000 UTC + Status code : Unset + Status message : + Span #1 + Trace ID : f30faffbde5fcf71432f89da1bf7bc14 + Parent ID : + ID : 6f1ff7f9cf4ec1c7 + Name : lets-go + Kind : Client + Start time : 2024-01-16 14:13:54.585877 +0000 UTC + End time : 2024-01-16 14:13:54.586 +0000 UTC + Status code : Unset + Status message : + ... + ``` + +6. を開いて、表中のサンプルの1つを選択すると、先ほど生成したトレースが表示されます。 + +7. 完了したら、たとえばControl-Cを使用してコレクターコンテナをシャットダウンします。 + +## この次のステップ + +このチュートリアルでは、OpenTelemetryコレクターを起動し、そこにテレメトリーを送信しました。 +次のステップとして、以下のことを検討してください。 + +- [コレクターのインストール](../installation/)について別の方法を試す +- コレクターの[デプロイ方法](../deployment/)についてさまざまな方法を学ぶ +- コレクターの[設定](/docs/collector/configuration)ファイルとその構造を理解する +- [レジストリ](/ecosystem/registry/?language=collector)で取得できるコンポーネントを探る +- [OpenTelemetry Collector Builder (OCB)を使ってカスタムコレクターをビルド](/docs/collector/custom-collector/)する方法を学ぶ + +[gobin]: https://pkg.go.dev/cmd/go#hdr-Environment_variables +[logs]: /docs/concepts/signals/logs/ +[metrics]: /docs/concepts/signals/metrics/ +[telemetrygen]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/cmd/telemetrygen +[traces]: /docs/concepts/signals/traces/ From 9ecec2000bfb90627c5c988fe3f2cf384b1a5c34 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 22 Aug 2024 12:40:41 -0400 Subject: [PATCH 2/3] [CI] Adjust submodule DEPTH uniformly across scripts (#5088) --- .github/workflows/auto-update-versions.yml | 2 +- .github/workflows/pr-actions.yml | 2 +- package.json | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/auto-update-versions.yml b/.github/workflows/auto-update-versions.yml index dd0d472476f6..1f36571febe8 100644 --- a/.github/workflows/auto-update-versions.yml +++ b/.github/workflows/auto-update-versions.yml @@ -12,7 +12,7 @@ jobs: runs-on: ubuntu-20.04 if: github.repository == 'open-telemetry/opentelemetry.io' env: - DEPTH: --depth 500 # submodule clone depth + DEPTH: --depth 999 # submodule clone depth steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/pr-actions.yml b/.github/workflows/pr-actions.yml index 57fffbee6d7a..28fdb9a22071 100644 --- a/.github/workflows/pr-actions.yml +++ b/.github/workflows/pr-actions.yml @@ -23,7 +23,7 @@ jobs: pull-requests: write env: - DEPTH: --depth 1000 # submodule clone depth + DEPTH: --depth 999 # submodule clone depth steps: - name: Extract action name diff --git a/package.json b/package.json index b737502604d4..5fc18e6f4a12 100644 --- a/package.json +++ b/package.json @@ -23,7 +23,7 @@ "_filename-error": "echo 'ERROR: the following files violate naming conventions; fix using: `npm run fix:filenames`'; echo; npm run -s _ls-bad-filenames; exit 1", "_get:no": "echo SKIPPING get operation", "_get:submodule:non-lang": "npm run _get:submodule -- content-modules/opentelemetry-specification themes/docsy", - "_get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 1}", + "_get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 999}", "_hugo": "hugo --cleanDestinationDir", "_install:dict": "npm install -D $(npm run -s _list:dict)", "_install:netlify-cli": "npm list netlify-cli || npm install -O netlify-cli", @@ -108,7 +108,7 @@ "update:other-pkg": "npm install --save-dev gulp@latest", "update:pkgs": "npx npm-check-updates -u", "update:submodule:lang": "npm run seq -- update:submodule _get:submodule:non-lang", - "update:submodule": "set -x && git submodule update --remote ${DEPTH:- --depth 1}" + "update:submodule": "set -x && git submodule update --remote ${DEPTH:- --depth 999}" }, "devDependencies": { "@cspell/dict-es-es": "^3.0.0", From f691980920d6ba0104c93e52590201c774a176f4 Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Thu, 22 Aug 2024 16:19:28 -0300 Subject: [PATCH 3/3] [pt] Add pt/content/docs/concepts/observability-primer.md (#4997) --- .../pt/docs/concepts/observability-primer.md | 156 ++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 content/pt/docs/concepts/observability-primer.md diff --git a/content/pt/docs/concepts/observability-primer.md b/content/pt/docs/concepts/observability-primer.md new file mode 100644 index 000000000000..e986b76ebb76 --- /dev/null +++ b/content/pt/docs/concepts/observability-primer.md @@ -0,0 +1,156 @@ +--- +title: Introdução à Observabilidade +description: Conceitos essenciais de Observabilidade +weight: 9 +cSpell:ignore: webshop +default_lang_commit: 6e3124135e38e749cdda15271d891813d6bc43db +--- + +## O que é Observabilidade? {#what-is-observability} + +Observabilidade permite que você compreenda um sistema de fora para dentro, +permitindo que você faça perguntas sobre ele sem precisar conhecer seu +funcionamento interno. Além disso, facilita a resolução de problemas e o +tratamento de novos problemas, ou seja, "problemas desconhecidos". Também ajuda +a responder à pergunta "Por que isso está acontecendo?" + +Para fazer essas perguntas sobre o seu sistema, sua aplicação deve estar +devidamente instrumentada. Ou seja, o código da aplicação deve emitir +[sinais](/docs/concepts/signals/) como +[rastros](/docs/concepts/signals/traces/), +[métricas](/docs/concepts/signals/metrics/) e +[logs](/docs/concepts/signals/logs/). Uma aplicação está devidamente +instrumentada quando a equipe de desenvolvimento não precisa adicionar mais +instrumentação para solucionar um problema, pois já tem todas as informações +necessárias. + +O [OpenTelemetry](/docs/what-is-opentelemetry/) é o mecanismo pelo qual o código +da aplicação é instrumentado para ajudar a tornar um sistema observável. + +## Confiabilidade e métricas + +**Telemetria** refere-se aos dados emitidos por um sistema e seu comportamento. +Esses dados podem vir na forma de [rastros](/docs/concepts/signals/traces/), +[métricas](/docs/concepts/signals/metrics/) e +[logs](/docs/concepts/signals/logs/). + +**Confiabilidade** responde a pergunta: "O serviço está fazendo o que os +usuários esperam que ele faça?" Um sistema pode estar ativo 100% do tempo, mas, +se quando um usuário clica em "Adicionar ao Carrinho" para adicionar um par de +sapatos pretos ao carrinho de compras, o sistema nem sempre adiciona sapatos +pretos, então o sistema pode ser **não** confiável. + +**Métricas** são dados numéricos sobre sua infraestrutura ou aplicação agregados +ao longo de um período de tempo. Exemplos incluem: taxa de erro do sistema, +utilização da CPU e taxa de requisições para um determinado serviço. Para mais +informações sobre métricas e como elas se relacionam com o OpenTelemetry, +consulte [Métricas](/docs/concepts/signals/metrics/). + +**SLI**, ou _Service Level Indicator_, representa uma medida do comportamento de +um serviço. Um bom SLI mede seu serviço do ponto de vista dos seus usuários. Um +exemplo de SLI pode ser a velocidade de carregamento de uma página web. + +**SLO**, ou _Service Level Objective_, representa a forma como confiabilidade é +comunicada para uma organização/outras equipes. Isso é feito associando um ou +mais SLIs ao valor de negócio. + +## Compreendendo rastreamento distribuído + +O rastreamento distribuído permite que você observe as requisições que se +propagam por sistemas complexos e distribuídos. O rastreamento distribuído +melhora a visibilidade da saúde da sua aplicação ou sistema, permitindo que você +faça depurações de comportamentos difíceis de reproduzir localmente. É essencial +para sistemas distribuídos, que costumam ter problemas não determinísticos ou +que são muito complicados de reproduzir localmente. + +Para entender o rastreamento distribuído, você precisa compreender a função de +cada um de seus componentes: logs, trechos e rastros. + +### Logs + +Um **log** é uma mensagem com registro de data e hora emitida por serviços ou +outros componentes. Ao contrário dos [rastros](#distributed-traces), eles não +são necessariamente associados a uma requisição de usuário ou transação +específica. Você pode encontrar logs em praticamente todos os softwares. Logs +foram muito utilizados no passado tanto por equipes de desenvolvimento quanto de +operação para entender o comportamento de um sistema. + +Exemplo de log: + +```text +I, [2021-02-23T13:26:23.505892 #22473] INFO -- : [6459ffe1-ea53-4044-aaa3-bf902868f730] Started GET "/" for ::1 at 2021-02-23 13:26:23 -0800 +``` + +Logs não são suficientes para rastrear a execução do código, pois geralmente não +apresentam informações contextuais, como de onde foram chamados. + +Eles se tornam muito mais úteis quando incluídos como parte de um +[trecho](#spans) ou quando são correlacionados com um rastro e um trecho. + +Para mais informações sobre logs e como eles se relacionam com o OpenTelemetry, +consulte [Logs](/docs/concepts/signals/logs/). + +### Trechos {#spans} + +Um **trecho** representa uma unidade de trabalho ou operação. Trechos rastreiam +operações específicas que uma requisição realiza, mostrando o que aconteceu +durante o tempo em que essa operação foi executada. + +Um trecho contém nome, dados relacionados ao tempo, +[mensagens de log estruturadas](/docs/concepts/signals/traces/#span-events) e +[outros metadados (ou seja, Atributos)](/docs/concepts/signals/traces/#attributes) +para fornecer informações sobre a operação sendo rastreada. + +#### Atributos de trecho + +Os atributos de trechos são metadados anexados a um trecho. + +A tabela a seguir contém exemplos de atributos de trecho: + +| Chave | Valor | +| :-------------------------- | :--------------------------------------------------------------------------------- | +| `http.request.method` | `"GET"` | +| `network.protocol.version` | `"1.1"` | +| `url.path` | `"/webshop/articles/4"` | +| `url.query` | `"?s=1"` | +| `server.address` | `"example.com"` | +| `server.port` | `8080` | +| `url.scheme` | `"https"` | +| `http.route` | `"/webshop/articles/:article_id"` | +| `http.response.status_code` | `200` | +| `client.address` | `"192.0.2.4"` | +| `client.socket.address` | `"192.0.2.5"` (o cliente passa por um proxy) | +| `user_agent.original` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | + +Para mais informações sobre trechos e como eles se relacionam com o +OpenTelemetry, consulte [Trecho](/docs/concepts/signals/traces/#spans). + +### Rastros distribuídos {#distributed-traces} + +Um **rastro distribuído**, mais comumente conhecido como um **rastro**, registra +os caminhos percorridos por requisições (feitas por uma aplicação ou usuário +final) enquanto se propagam por arquiteturas com múltiplos serviços, como +aplicações de microsserviços e _serverless_. + +Um rastro é composto de um ou mais trechos. O primeiro trecho representa o +trecho raiz. Cada trecho raiz representa uma requisição do início ao fim. Os +trechos abaixo do trecho raiz fornecem um contexto mais aprofundado do que +ocorre durante uma requisição (ou quais etapas compõem uma requisição). + +Sem rastreamento, encontrar a causa raiz de problemas de desempenho em um +sistema distribuído pode ser desafiador. O rastreamento torna a depuração e o +entendimento de sistemas distribuídos menos assustador, criando um passo a passo +do que acontece dentro de uma requisição à medida que ela flui por um sistema +distribuído. + +Muitos _backends_ de Observabilidade visualizam rastros como diagramas em +cascata que se parecem com isto: + +![Exemplo de Rastro](/img/waterfall-trace.svg 'Diagrama em cascata de rastreamento') + +Os diagramas em cascata mostram a relação pai-filho entre um trecho raiz e seus +trechos filhos. Quando um trecho encapsula outro trecho, isso também representa +uma relação aninhada. + +Para mais informações sobre rastros e como eles se relacionam com o +OpenTelemetry, consulte [Rastros](/docs/concepts/signals/traces/).